Skip to contents

Dot Plot for Beta Diversity Change Tests Over Time

Source: R/generate_beta_per_time_dotplot_long.R
generate_beta_per_time_dotplot_long.Rd

Visualizes results from longitudinal beta diversity change tests as dot plots.

Usage

generate_beta_per_time_dotplot_long(
  data.obj,
  test.list,
  group.var,
  time.var,
  t0.level,
  ts.levels,
  base.size = 16,
  theme.choice = "bw",
  custom.theme = NULL,
  palette = rev(c("white", "#92c5de", "#0571b0", "#f4a582", "#ca0020")),
  pdf = FALSE,
  pdf.wid = 7,
  pdf.hei = 5
)

Arguments

data.obj

A MicrobiomeStat data object, which is a list containing at minimum the following components:

  • feature.tab: A matrix of feature abundances (taxa/genes as rows, samples as columns)

  • meta.dat: A data frame of sample metadata (samples as rows)

Optional components include:

  • feature.ann: A matrix/data frame of feature annotations (e.g., taxonomy)

  • tree: A phylogenetic tree object (class "phylo")

  • feature.agg.list: Pre-aggregated feature tables by taxonomy

Data objects can be created using converters like mStat_convert_phyloseq_to_data_obj or importers like mStat_import_qiime2_as_data_obj.

test.list

A list of test results from generate_beta_change_per_time_test_long.

group.var

Character string specifying the group variable for comparisons.

time.var

Character string specifying the column name in meta.dat containing the time variable. Required for longitudinal and paired analyses. Supports character/factor labels (e.g., "baseline", "week4") and numeric values. Some trend/volatility methods require numeric or coercible-to-numeric time values.

t0.level

Character or numeric value specifying the baseline time point for longitudinal or paired analyses. Should match a value in the time.var column.

ts.levels

Character vector specifying the follow-up time points for longitudinal or paired analyses. Should match values in the time.var column.

base.size

Numeric value specifying the base font size for plot text elements. Default is typically 16.

theme.choice

Character string specifying the ggplot2 theme to use. Options include:

  • "bw": Black and white theme (theme_bw)

  • "classic": Classic theme (theme_classic)

  • "gray": Gray theme (theme_gray)

  • "light": Light theme (theme_light)

  • "dark": Dark theme (theme_dark)

  • "minimal": Minimal theme (theme_minimal)

  • "void": Void theme (theme_void)

  • "prism": GraphPad Prism-like theme

Can also use a custom ggplot2 theme object via custom.theme.

custom.theme

A custom ggplot2 theme object to override theme.choice. Should be created using ggplot2::theme() or a complete theme function.

palette

Character vector of colors or a named palette for the plot. If NULL, uses default MicrobiomeStat color scheme. Can be:

  • A vector of color codes (e.g., c("#E41A1C", "#377EB8"))

  • A palette name recognized by the plotting function

pdf

Logical. If TRUE, saves the plot(s) to PDF file(s) in the current working directory. Default is TRUE.

pdf.wid

Numeric value specifying the width of PDF output in inches. Default is typically 11.

pdf.hei

Numeric value specifying the height of PDF output in inches. Default is typically 8.5.

Value

A list of ggplot objects, each representing a dot plot for a specific group. The plots can be further customized or directly rendered.

Details

The function uses ggplot2 to create dot plots, with options for customizing themes and aesthetics. It visualizes the significance and magnitude of changes in beta diversity indices, indicated by color and size of the dots. The function allows for detailed customization of plot features, including base font size and theme choice.

The function prepares data by merging and transforming the results from `generate_beta_test_long` to fit the plotting structure. It handles the display of statistical significance using color coding and sizes dots based on the estimate value from the statistical test.

Examples

if (FALSE) { # \dontrun{
data(subset_T2D.obj)
result1 <- generate_beta_change_per_time_test_long(
  data.obj = subset_T2D.obj,
  dist.obj = NULL,
  time.var = "visit_number_num",
  t0.level = unique(subset_T2D.obj$meta.dat$visit_number_num)[1],
  ts.levels = unique(subset_T2D.obj$meta.dat$visit_number_num)[-1],
  subject.var = "subject_id",
  group.var = "subject_race",
  adj.vars = NULL,
  dist.name = c('BC', 'Jaccard')
)

# Visualizing the results for the Type 2 Diabetes dataset
dotplot_T2D <- generate_beta_per_time_dotplot_long(
  data.obj = subset_T2D.obj,
  test.list = result1,
  group.var = "subject_race",
  time.var = "visit_number_num",
  t0.level = unique(subset_T2D.obj$meta.dat$visit_number_num)[1],
  ts.levels = unique(subset_T2D.obj$meta.dat$visit_number_num)[-1],
)

data(ecam.obj)
dist.obj <- mStat_calculate_beta_diversity(ecam.obj, c('BC', 'Jaccard'))
result2 <- generate_beta_change_per_time_test_long(
  data.obj = ecam.obj,
  dist.obj = dist.obj,
  time.var = "month",
  t0.level = unique(ecam.obj$meta.dat$month)[1],
  ts.levels = unique(ecam.obj$meta.dat$month)[-1],
  subject.var = "subject.id",
  group.var = "diet",
  adj.vars = NULL,
  dist.name = c('BC', 'Jaccard')
)

# Visualizing the results for the ECAM dataset
dotplot_ecam <- generate_beta_per_time_dotplot_long(
  data.obj = ecam.obj,
  test.list = result2,
  group.var = "delivery",
  time.var = "month",
  t0.level = unique(ecam.obj$meta.dat$month)[1],
  ts.levels = unique(ecam.obj$meta.dat$month)[-1],
  base.size = 15
)
} # }