Runs ALDEx2 between two groups and shows the differentially abundant taxa as a heatmap (with ComplexHeatmap) of their CLR values, annotated with the effect size and the p-value.
Usage
aldex_heatmap_plot(
table,
metadata,
group_col,
effect_threshold = 0,
pval_threshold = 0.05,
p_adjust_method = "BH",
mc_samples = 128,
cluster_rows = FALSE,
cluster_columns = FALSE,
heatmap_colors = NULL,
effect_colors = c("#009E73", "white", "#CC79A7"),
pvalue_colors = c(`<0.001` = "#000000", `<0.01` = "#D55E00", `<0.05` = "#F0E442",
`>0.05` = "grey85"),
group_colors = NULL,
save_table = FALSE,
table_filename = "aldex_pval_effect.txt",
draw = TRUE
)Arguments
- table
A data frame with taxa in rows and samples in columns. The last column must be named
taxonomy, containing full taxonomic strings.- metadata
A data frame containing sample metadata. Its first column must hold the sample IDs (the column names of
table).- group_col
Character. Name of the column in
metadatathat defines the groups. It must have exactly two groups.- effect_threshold
Numeric. Minimum absolute effect size to retain. Default
0(no effect-size filter), so by default the heatmap shows the same taxa thataldex_volcano_plotcolors as significant.- pval_threshold
Numeric or
NULL. P-value cutoff (afterp_adjust_method) to keep only significant taxa. Default0.05. IfNULL, onlyeffect_thresholdis applied.- p_adjust_method
Character.
"BH"(default) or"none": use the Benjamini-Hochberg adjusted p-values of ALDEx2 (wi.eBH) or the raw ones (wi.ep) forpval_thresholdand the p-value annotation. ALDEx2 only computes the BH correction.- mc_samples
Integer. Number of ALDEx2 Monte Carlo instances. Default
128(ALDEx2's default), recommended for final analyses. Fewer instances are faster but the p-values and effect sizes are less stable (e.g.16for a quick look); callset.seed()before the function to make the result reproducible.- cluster_rows
Logical. Cluster heatmap rows (default
FALSE).- cluster_columns
Logical. Cluster heatmap columns (default
FALSE).- heatmap_colors
Controls the color scale of the main heatmap body (CLR values). Three options:
NULL(default, same as"viridis") uses a sequential colorblind-friendly viridis scale (the same family used inabundance_heatmap_plot), with range computed automatically from the data; a preset name string:"viridis"or one of the diverging presets"BuOr"(blue-orange),"BuVm"(blue-vermillion),"BuPk"(blue-pink),"GnPk"(green-pink); or acirclize::colorRamp2function for full manual control.- effect_colors
Three colors for the effect size annotation strip: negative, zero and positive effect (mapped to -1.5, 0 and 1.5). Default
c("#009E73", "white", "#CC79A7")(green-white-pink, colorblind-friendly, distinct from the heatmap body and p-value defaults). Acirclize::colorRamp2()function is also accepted.- pvalue_colors
Named vector of colors for the p-value annotation strip, with names
"<0.001","<0.01","<0.05"and">0.05". Default black/vermillion/yellow/grey (distinct from the heatmap body and effect size defaults). A list with one such vector named"p-value"is also accepted.- group_colors
Optional character vector of colors for the group annotation, one per group, named after the groups or in their order. If
NULL(default), the colorblind-friendly Okabe-Ito palette is used (orange/blue for two groups).- save_table
Logical. If
TRUE, saves the ALDEx2 results of the plotted taxa (effect size,diff.btwand p-value category) as a tab-delimited file. DefaultFALSE.effectanddiff.btware saved as ALDEx2 returns them (second group in alphabetical order minus the first); thehigher_incolumn says in which group each taxon is higher.- table_filename
Character. Name or path of the saved file (used when
save_table = TRUE). Default"aldex_pval_effect.txt".- draw
Logical. If
TRUE(default), the heatmap is drawn on the current device. UseFALSEto only build the returned grob without drawing it.
Value
Invisibly, a gTree (grid grob) with the heatmap. Printing it
(e.g. typing its name) draws the heatmap; it can also be combined with
other plots (e.g. cowplot::plot_grid(),
patchwork::wrap_elements()).
Examples
table_path <- system.file("extdata", "subset_table_bacteria.txt", package = "MicroBioMeta")
table <- read.delim(table_path, row.names = 1, check.names = FALSE)
metadata_path <- system.file("extdata", "subset_metadata_bacteria.txt", package = "MicroBioMeta")
metadata <- read.delim(metadata_path, check.names = FALSE)
# group_col must have exactly two groups; Location has two
# (Rhizosphere and Roots) in the bundled example data. Here taxa are
# filtered by effect size alone (pval_threshold = NULL), since this small
# (46-sample) dataset has few taxa with significant p-values.
aldex_heatmap_plot(
table = table,
metadata = metadata,
group_col = "Location",
mc_samples = 16,
effect_threshold = 0.5,
pval_threshold = NULL
)
#> Warning: values are unreliable when estimated with so few MC smps
# All the colors have colorblind-friendly defaults, but each can be set by
# hand: group_colors (difference bars, named after the groups),
# effect_colors (negative, zero and positive effect size), pvalue_colors
# (one color per p-value class) and heatmap_colors (median clr values)
# \donttest{
aldex_heatmap_plot(
table = table,
metadata = metadata,
group_col = "Location",
mc_samples = 16,
effect_threshold = 0.5,
pval_threshold = NULL,
group_colors = c(Rhizosphere = "#56B4E9", Roots = "#009E73"),
effect_colors = c("#0072B2", "white", "#E69F00"),
pvalue_colors = c(
"<0.001" = "black", "<0.01" = "grey30",
"<0.05" = "grey60", ">0.05" = "grey90"
),
heatmap_colors = "BuOr"
)
#> Warning: values are unreliable when estimated with so few MC smps
# }