Generate boxplot comparing change in specified alpha diversity index — generate_alpha_change_boxplot

This function generates a boxplot comparing the change in a specified alpha diversity index between two time points. The change can be calculated as the log or the absolute value. Several optional arguments are available for customizing the output, such as strata or group variables.

Usage

generate_alpha_change_boxplot_pair(
  data.obj,
  alpha.obj = NULL,
  alpha.name = c("shannon", "observed_species"),
  depth = NULL,
  subject.var,
  time.var,
  group.var = NULL,
  strata.var = NULL,
  adj.vars = NULL,
  change.base = NULL,
  alpha.change.func = c("log fold change"),
  base.size = 16,
  theme.choice = "bw",
  custom.theme = NULL,
  palette = NULL,
  pdf = TRUE,
  file.ann = NULL,
  pdf.wid = 11,
  pdf.hei = 8.5,
  ...
)

Arguments

data.obj

A list object in a format specific to MicrobiomeStat, which can include components such as feature.tab (matrix), feature.ann (matrix), meta.dat (data.frame), tree, and feature.agg.list (list). The data.obj can be converted from other formats using several functions from the MicrobiomeStat package, including: 'mStat_convert_DGEList_to_data_obj', 'mStat_convert_DESeqDataSet_to_data_obj', 'mStat_convert_phyloseq_to_data_obj', 'mStat_convert_SummarizedExperiment_to_data_obj', 'mStat_import_qiime2_as_data_obj', 'mStat_import_mothur_as_data_obj', 'mStat_import_dada2_as_data_obj', and 'mStat_import_biom_as_data_obj'. Alternatively, users can construct their own data.obj. Note that not all components of data.obj may be required for all functions in the MicrobiomeStat package.

alpha.obj

An optional list containing pre-calculated alpha diversity indices. If NULL (default), alpha diversity indices will be calculated using mStat_calculate_alpha_diversity function from MicrobiomeStat package.

alpha.name

The alpha diversity index to be plotted. Supported indices include "shannon", "simpson", "observed_species", "chao1", "ace", and "pielou". Previously named as `alpha.index`.

depth

An integer specifying the sequencing depth for the "Rarefy" and "Rarefy-TSS" methods. If NULL, no rarefaction is performed.

subject.var

The variable in the metadata table that represents the subject.

time.var

The variable in the metadata table that represents the time.

group.var

(Optional) The variable in the metadata table that represents the grouping factor.

strata.var

(Optional) The variable in the metadata table that represents the stratification factor.

adj.vars

A character vector of variable names to be used for adjustment.

change.base

The base time for calculating the change in alpha diversity.

alpha.change.func

Function or method for calculating change in alpha diversity between two timepoints. This allows flexible options to quantify change:

- If a function is provided: The function will be applied to compare alpha diversity at timepoint t vs baseline t0. The function should take two arguments representing the alpha diversity values at t and t0. For instance, a custom function to calculate the percentage change might look like:


      percentage_change <- function(t, t0) {
        return ((t - t0) / t0) * 100
      }

You can then pass this function as the value for `alpha.change.func`.

- If a string is provided, the following options are supported: - 'log fold change': Calculates the log2 fold change of alpha diversity at t compared to t0. - 'absolute change': Calculates the absolute difference in alpha diversity at t compared to t0. - Any other value: A warning will be given that the provided method is not recognized, and the default method ('absolute change') will be used.

- Default behavior (if no recognized string or function is provided) is to compute the absolute difference between t and t0.

base.size

The base font size for the plot.

theme.choice

Plot theme choice. Specifies the visual style of the plot. Can be one of the following pre-defined themes: - "prism": Utilizes the ggprism::theme_prism() function from the ggprism package, offering a polished and visually appealing style. - "classic": Applies theme_classic() from ggplot2, providing a clean and traditional look with minimal styling. - "gray": Uses theme_gray() from ggplot2, which offers a simple and modern look with a light gray background. - "bw": Employs theme_bw() from ggplot2, creating a classic black and white plot, ideal for formal publications and situations where color is best minimized. - "light": Implements theme_light() from ggplot2, featuring a light theme with subtle grey lines and axes, suitable for a fresh, modern look. - "dark": Uses theme_dark() from ggplot2, offering a dark background, ideal for presentations or situations where a high-contrast theme is desired. - "minimal": Applies theme_minimal() from ggplot2, providing a minimalist theme with the least amount of background annotations and colors. - "void": Employs theme_void() from ggplot2, creating a blank canvas with no axes, gridlines, or background, ideal for custom, creative plots. Each theme option adjusts various elements like background color, grid lines, and font styles to match the specified aesthetic. Default is "bw", offering a universally compatible black and white theme suitable for a wide range of applications.

custom.theme

A custom ggplot theme provided as a ggplot2 theme object. This allows users to override the default theme and provide their own theme for plotting. Custom themes are useful for creating publication-ready figures with specific formatting requirements.

To use a custom theme, create a theme object with ggplot2::theme(), including any desired customizations. Common customizations for publication-ready figures might include adjusting text size for readability, altering line sizes for clarity, and repositioning or formatting the legend. For example:

“`r my_theme <- ggplot2::theme( axis.title = ggplot2::element_text(size=14, face="bold"), # Bold axis titles with larger font axis.text = ggplot2::element_text(size=12), # Slightly larger axis text legend.position = "top", # Move legend to the top legend.background = ggplot2::element_rect(fill="lightgray"), # Light gray background for legend panel.background = ggplot2::element_rect(fill="white", colour="black"), # White panel background with black border panel.grid.major = ggplot2::element_line(colour = "grey90"), # Lighter color for major grid lines panel.grid.minor = ggplot2::element_blank(), # Remove minor grid lines plot.title = ggplot2::element_text(size=16, hjust=0.5) # Centered plot title with larger font ) “`

Then pass `my_theme` to `custom.theme`. If `custom.theme` is NULL (the default), the theme is determined by `theme.choice`. This flexibility allows for both easy theme selection for general use and detailed customization for specific presentation or publication needs.

palette

An optional parameter specifying the color palette to be used for the plot. It can be either a character string specifying the name of a predefined palette or a vector of color codes in a format accepted by ggplot2 (e.g., hexadecimal color codes). Available predefined palettes include 'npg', 'aaas', 'nejm', 'lancet', 'jama', 'jco', and 'ucscgb', inspired by various scientific publications and the `ggsci` package. If `palette` is not provided or an unrecognized palette name is given, a default color palette will be used. Ensure the number of colors in the palette is at least as large as the number of groups being plotted.

pdf

(Optional) A boolean indicating whether to save the output as a PDF file.

file.ann

(Optional) A string for annotating the output file name.

pdf.wid

The width of the output PDF file. Default is 11.

pdf.hei

The height of the output PDF file. Default is 8.5.

...

(Optional) Additional arguments to pass to the plotting function.

Value

A boxplot displaying the change in the specified alpha diversity index between two time points, stratified by the specified grouping and/or strata variables (if provided). The boxplot will be saved as a PDF if `pdf` is set to `TRUE`.

Details

This parameter allows flexible quantification of how alpha diversity changes from baseline. Log-ratio is commonly used to compare relative difference. Absolute difference indicates the magnitude of change. Custom functions can also be supplied to calculate change as needed.

This function extracts metadata, calculates alpha diversity for specified indices, compares values between two timepoints, applies log2 fold change by default, visualizes the change using boxplots and optional faceting and saving as PDF.

Examples

if (FALSE) { # \dontrun{
library(vegan)
data(peerj32.obj)
# Example 1: Both group.var and strata.var are NULL
generate_alpha_change_boxplot_pair(
  data.obj = peerj32.obj,
  alpha.obj = NULL,
  alpha.name = "simpson",
  subject.var = "subject",
  time.var = "time",
  group.var = NULL,
  strata.var = NULL,
  adj.vars = NULL,
  change.base = "1",
  alpha.change.func = "absolute change",
  base.size = 16,
  theme.choice = "bw",
  palette = "lancet",
  pdf = TRUE,
  file.ann = "no_groups",
  pdf.wid = 11,
  pdf.hei = 8.5
)
# Example 2: Only group.var is non-NULL
generate_alpha_change_boxplot_pair(
  data.obj = peerj32.obj,
  alpha.obj = NULL,
  alpha.name = "simpson",
  subject.var = "subject",
  time.var = "time",
  group.var = "group",
  strata.var = NULL,
  adj.vars = NULL,
  change.base = "1",
  alpha.change.func = "log fold change",
  base.size = 16,
  theme.choice = "classic",
  palette = "npg",
  pdf = TRUE,
  file.ann = "group_only",
  pdf.wid = 11,
  pdf.hei = 8.5
)
# Example 3: Both group.var and strata.var are non-NULL
generate_alpha_change_boxplot_pair(
  data.obj = peerj32.obj,
  alpha.obj = NULL,
  alpha.name = "simpson",
  subject.var = "subject",
  time.var = "time",
  group.var = "group",
  strata.var = "sex",
  adj.vars = NULL,
  change.base = "1",
  alpha.change.func = "log fold change",
  base.size = 16,
  theme.choice = "gray",
  palette = "aaas",
  pdf = TRUE,
  file.ann = "group_and_strata",
  pdf.wid = 11,
  pdf.hei = 8.5
)
# Example 4: Both group.var and adj.vars are non-NULL, strata.var is NULL
generate_alpha_change_boxplot_pair(
  data.obj = peerj32.obj,
  alpha.obj = NULL,
  alpha.name = "simpson",
  subject.var = "subject",
  time.var = "time",
  group.var = "group",
  strata.var = NULL,
  adj.vars = c("sex"),
  change.base = "1",
  alpha.change.func = "absolute change",
  base.size = 16,
  theme.choice = "minimal",
  palette = "jama",
  pdf = TRUE,
  file.ann = "group_and_adj",
  pdf.wid = 11,
  pdf.hei = 8.5
)

data("subset_pairs.obj")
generate_alpha_change_boxplot_pair(
  data.obj = subset_pairs.obj,
  alpha.obj = NULL,
  alpha.name = c("simpson"),
  subject.var = "MouseID",
  time.var = "Antibiotic",
  group.var = "Sex",
  strata.var = NULL,
  adj.vars = NULL,
  change.base = "Baseline",
  alpha.change.func = "log fold change",
  base.size = 16,
  theme.choice = "bw",
  palette = "lancet",
  pdf = TRUE,
  file.ann = NULL,
  pdf.wid = 11,
  pdf.hei = 8.5
)
} # }