Skip to contents

This function is designed to perform beta change tests on longitudinal microbiome data. It integrates multiple components of the MicrobiomeStat package to process and analyze the data, focusing on beta diversity changes over time within subjects.

Usage

generate_beta_change_per_time_test_long(
  data.obj = NULL,
  dist.obj = NULL,
  time.var,
  t0.level = NULL,
  ts.levels = NULL,
  subject.var,
  group.var = NULL,
  adj.vars = NULL,
  dist.name = c("BC", "Jaccard"),
  ...
)

Arguments

data.obj

A list object formatted specifically for MicrobiomeStat, potentially including components like feature.tab (matrix), feature.ann (matrix), meta.dat (data.frame), tree, and feature.agg.list (list). This object can be derived from various formats using MicrobiomeStat functions such as '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'.

dist.obj

A distance matrix between samples, typically generated using mStat_calculate_beta_diversity. If NULL, the function will compute beta diversity from data.obj.

time.var

A character string identifying the column in metadata that contains time information. This column should list time points for each sample, necessary for ordering and linking samples over time for the same subject.

t0.level

A baseline time point for longitudinal analysis, specified as a character or numeric value, e.g., "week_0" or 0.

ts.levels

A vector of character strings indicating follow-up time points, such as c("week_4", "week_8").

subject.var

The name of the column in metadata containing the subject IDs. This should uniquely identify each subject in the study. Required to identify samples that belong to the same subject.

group.var

A character string naming the column in metadata that contains the grouping variable, which can be used for color mapping in plots. Optional; can be NULL.

adj.vars

A vector of character strings naming columns in metadata to include as covariates for adjusting the distance matrix before ordination. Can be empty or NULL if no adjustment is needed.

dist.name

A vector of character strings specifying which beta diversity indices to calculate. Supported indices include "BC" (Bray-Curtis), "Jaccard", "UniFrac" (unweighted), "GUniFrac" (generalized UniFrac), "WUniFrac" (weighted UniFrac), and "JS" (Jensen-Shannon divergence). If a specified index is not present in dist.obj, it will be computed internally. An error is returned if an unsupported index is specified.

...

Additional arguments passed to underlying functions.

Value

A list of test results, structured to facilitate further analysis and visualization.

See also

Related functions in MicrobiomeStat for data preparation and beta diversity calculation, such as mStat_calculate_beta_diversity, mStat_calculate_PC, and data conversion functions like mStat_convert_DGEList_to_data_obj.

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],
)

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 = c("sample_body_site", "subject_gender"),
  dist.name = c('BC', 'Jaccard')
)

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
)
} # }