Runs ALDEx2 between two groups and plots the results as a volcano plot or an effect size plot.
Usage
aldex_volcano_plot(
table,
metadata,
group_col,
type = "volcano",
mc_samples = 128,
col_inf = "#56B4E9",
col_sup = "#E69F00",
threshold_lower = -1.5,
threshold_upper = 1.5,
cond = NULL,
pval_threshold = 0.05,
p_adjust_method = "BH",
show_labels = TRUE,
taxa = NULL,
x_axis_title = NULL,
y_axis_title = NULL,
label_size = 3.5,
filter_uncultured = FALSE,
save_table = FALSE,
table_filename = "aldex_pval_effect.txt"
)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.- type
Type of plot to generate:
"volcano"(default, volcano plot) or"effect"(effect-size plot). Case-insensitive.- 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.- col_inf
Character. Color of the taxa lower in
cond. Default"#56B4E9"(Okabe-Ito blue).- col_sup
Character. Color of the taxa higher in
cond. Default"#E69F00"(Okabe-Ito orange).- threshold_lower
Numeric. Lower cutoff on the x-axis (effect size or difference between groups), drawn as a dashed line. Default
-1.5.- threshold_upper
Numeric. Upper cutoff on the x-axis (effect size or difference between groups), drawn as a dashed line. Default
1.5.- cond
Name of the reference condition for the plot labels: positive values on the x-axis mean higher in
cond. DefaultNULL, the condition of the first sample intable.- pval_threshold
Numeric. P-value cutoff (after
p_adjust_method), drawn as the dashed horizontal line. Default0.05.- 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) for the y-axis andpval_threshold. ALDEx2 only computes the BH correction.- show_labels
Logical. If
TRUE(default), shows the "Higher in"/"Lower in"condlabels (only fortype = "effect").- taxa
Optional data frame with columns
Feature.IDandTaxon, used to label the taxa. IfNULL(default), thetaxonomycolumn oftableis used.- x_axis_title, y_axis_title
Titles for the x- and y-axis. Default
NULL:"Effect size"("effect") or log2 fold change ("volcano") on x, and the (adjusted) p-value on y.- label_size
Numeric. Font size of the taxon labels drawn on significant points in the "volcano" plot. Default
3.5.- filter_uncultured
Logical. If
TRUE, taxa whose name contains "uncultured"/"unculture" are still plotted as points but not labelled, keeping the volcano plot's text annotations to named taxa. DefaultFALSE.- save_table
Logical. If
TRUE, saves the ALDEx2 results table as a tab-delimited file. DefaultFALSE.effectanddiff.btware saved as ALDEx2 returns them (second group in alphabetical order minus the first); in the plot, positive means higher incond.- table_filename
Character. Name or path of the saved file (used when
save_table = TRUE). Default"aldex_pval_effect.txt".
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
aldex_volcano_plot(
table = table,
metadata = metadata,
group_col = "Location",
mc_samples = 16,
type = "effect",
col_inf = "#56B4E9",
col_sup = "#E69F00",
threshold_lower = -0.5,
threshold_upper = 0.5,
cond = "Rhizosphere",
show_labels = TRUE
)
#> Warning: values are unreliable when estimated with so few MC smps