Generate Beta Diversity Ordination Plots for Longitudinal Data

Creates ordination plots (PCoA/NMDS) showing sample trajectories over time, with arrows connecting time points for each subject.

Usage

generate_beta_ordination_long(
  data.obj = NULL,
  dist.obj = NULL,
  pc.obj = NULL,
  subject.var,
  time.var,
  t0.level = NULL,
  ts.levels = NULL,
  group.var = NULL,
  strata.var = NULL,
  adj.vars = NULL,
  dist.name = c("BC", "Jaccard"),
  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 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.

dist.obj

A list of pre-calculated distance matrices. If NULL and distances are needed, they will be calculated automatically. List names should match dist.name (e.g., "BC" for Bray-Curtis). See mStat_calculate_beta_diversity.

pc.obj

A list containing dimension reduction results from mStat_calculate_PC. If NULL, PCoA is performed automatically.

subject.var

Character string specifying the column name in meta.dat that uniquely identifies each subject or sample unit. Required for longitudinal and paired designs to track repeated measurements.

time.var

Character string specifying the column name in meta.dat containing the time variable. Required for longitudinal and paired analyses. Should be a factor or character with meaningful time point labels.

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.

group.var

Character string specifying the column name in meta.dat containing the grouping variable (e.g., treatment, condition, phenotype). Used for between-group comparisons.

strata.var

Character string specifying the column name in meta.dat for stratification. When provided, analyses and visualizations will be performed separately within each stratum (e.g., by site, batch, or sex).

adj.vars

Character vector specifying column names in meta.dat to be used as covariates for adjustment in statistical models. These variables will be included as fixed effects.

dist.name

Character vector specifying which distance metrics to use. Options depend on available methods:

"BC": Bray-Curtis dissimilarity
"Jaccard": Jaccard distance
"UniFrac": Unweighted UniFrac (requires tree)
"GUniFrac": Generalized UniFrac (requires tree)
"WUniFrac": Weighted UniFrac (requires tree)
"JS": Jensen-Shannon divergence

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)
"minimal": Minimal theme (theme_minimal)
"prism": GraphPad Prism-like theme
"nature": Nature journal style
"light": Light theme (theme_light)

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.

file.ann

Character string for additional annotation to append to output filenames. Useful for distinguishing multiple outputs.

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.

...

Additional arguments passed to underlying functions.

Value

A list of ggplot2 objects representing the beta ordination plots.

Examples

if (FALSE) { # \dontrun{
data(subset_T2D.obj)
generate_beta_ordination_long(
  data.obj = subset_T2D.obj,
  dist.obj = NULL,
  pc.obj = NULL,
  subject.var = "subject_id",
  time.var = "visit_number_num",
  t0.level = NULL,
  ts.levels = NULL,
  group.var = "subject_race",
  strata.var = NULL,
  adj.vars = NULL,
  dist.name = 'BC',
  base.size = 12,
  theme.choice = "bw",
  custom.theme = NULL,
  palette = NULL,
  pdf = TRUE,
  file.ann = NULL,
  pdf.wid = 11,
  pdf.hei = 8.5
)

generate_beta_ordination_long(
  data.obj = subset_T2D.obj,
  dist.obj = NULL,
  pc.obj = NULL,
  subject.var = "subject_id",
  time.var = "visit_number_num",
  t0.level = NULL,
  ts.levels = NULL,
  group.var = "subject_race",
  strata.var = "subject_gender",
  adj.vars = NULL,
  dist.name = 'BC',
  base.size = 12,
  theme.choice = "bw",
  custom.theme = NULL,
  palette = NULL,
  pdf = TRUE,
  file.ann = NULL,
  pdf.wid = 11,
  pdf.hei = 8.5
)

generate_beta_ordination_long(
  data.obj = subset_T2D.obj,
  dist.obj = NULL,
  pc.obj = NULL,
  subject.var = "subject_id",
  time.var = "visit_number_num",
  t0.level = NULL,
  ts.levels = NULL,
  group.var = NULL,
  strata.var = NULL,
  adj.vars = NULL,
  dist.name = 'BC',
  base.size = 12,
  theme.choice = "bw",
  custom.theme = NULL,
  palette = NULL,
  pdf = TRUE,
  file.ann = NULL,
  pdf.wid = 11,
  pdf.hei = 8.5
)

data(ecam.obj)
dist.obj <- mStat_calculate_beta_diversity(ecam.obj, "BC")
pc.obj <- mStat_calculate_PC(dist.obj)
generate_beta_ordination_long(
  data.obj = ecam.obj,
  dist.obj = dist.obj,
  pc.obj = pc.obj,
  subject.var = "subject.id",
  time.var = "month",
  t0.level = "0",
  ts.levels = as.character(sort(as.numeric(unique(ecam.obj$meta.dat$month))))[2:10],
  group.var = "diet",
  strata.var = NULL,
  adj.vars = NULL,
  dist.name = 'BC',
  base.size = 16,
  theme.choice = "bw",
  custom.theme = NULL,
  palette = NULL,
  pdf = TRUE,
  file.ann = NULL,
  pdf.wid = 11,
  pdf.hei = 8.5
)
generate_beta_ordination_long(
  data.obj = ecam.obj,
  dist.obj = dist.obj,
  pc.obj = pc.obj,
  subject.var = "subject.id",
  time.var = "month_num",
  t0.level = NULL,
  ts.levels = NULL,
  group.var = NULL,
  strata.var = NULL,
  adj.vars = NULL,
  dist.name = 'BC',
  base.size = 16,
  theme.choice = "bw",
  custom.theme = NULL,
  palette = NULL,
  pdf = TRUE,
  file.ann = NULL,
  pdf.wid = 11,
  pdf.hei = 8.5
)
} # }

Usage

Arguments

Value

See also

Examples