Compare alpha diversity between time points — generate_alpha_change_per_time_test

This function performs paired tests to compare alpha diversity metrics between two time points in a microbiome dataset.

Usage

generate_alpha_change_per_time_test_long(
  data.obj,
  alpha.obj = NULL,
  alpha.name = NULL,
  depth = NULL,
  time.var,
  t0.level,
  ts.levels,
  subject.var,
  group.var,
  adj.vars = NULL,
  alpha.change.func = "log fold change"
)

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.
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 analyzed. Supported indices include "shannon", "simpson", "observed_species", "chao1", "ace", and "pielou".
depth: An integer specifying the sequencing depth for the "Rarefy" and "Rarefy-TSS" methods. If NULL, no rarefaction is performed.
time.var: Character string specifying the column name in metadata containing time values for each sample. Required to identify pairs of time points to calculate changes between.
t0.level: The baseline time point against which changes are measured.
ts.levels: An array of time points to compare against the baseline.
subject.var: Character string specifying the column name in metadata containing unique subject IDs. Required to pair samples from the same subject across time points.
group.var: Character string specifying the column name in metadata containing grouping categories. Used as a predictor in the models to test for differences in changes between groups. Optional, can be NULL.
adj.vars: Character vector specifying column names in metadata containing covariates to adjust for in the linear models. Optional, can be left NULL if no adjustment is needed.
alpha.change.func: Function or method for calculating change in alpha diversity between two timepoints. Supports custom functions or predefined methods like 'log fold change'.

Value

A list of tables, one for each alpha diversity metric, summarizing the results of the statistical tests.

Details

The function calculates alpha diversity at each time point and then compares these values to assess changes over time. It supports various methods for calculating the change in alpha diversity, including log fold change.

Users can specify a number of parameters, including the alpha diversity metric to be analyzed, the depth for rarefaction, and covariates for adjustment. The function is flexible and can accommodate different data structures and analysis requirements.

The function calculates alpha diversity for each time point and then compares these values to assess changes. The comparison can be done using different methods, such as log fold change. The function is designed to be flexible and can handle various data structures and analysis requirements.

Examples

if (FALSE) { # \dontrun{
library(vegan)
data(peerj32.obj)
# Perform the longitudinal alpha diversity test for the peerj32 dataset
alpha_test_results_peerj32 <- generate_alpha_change_per_time_test_long(
  data.obj = peerj32.obj,
  alpha.obj = NULL,
  alpha.name = c("shannon", "simpson", "observed_species", "chao1", "ace", "pielou"),
  time.var = "time",
  t0.level = unique(peerj32.obj$meta.dat$time)[1],
  ts.levels = unique(peerj32.obj$meta.dat$time)[-1],
  subject.var = "subject",
  group.var = "sex",
  adj.vars = "group",
  alpha.change.func = "log fold change"
)
# Generate dot plots for the peerj32 dataset results
generate_alpha_per_time_dotplot_long(
  data.obj = peerj32.obj,
  test.list = alpha_test_results_peerj32,
  group.var = "sex",
  time.var = "time",
  t0.level = unique(peerj32.obj$meta.dat$time)[1],
  ts.levels = unique(peerj32.obj$meta.dat$time)[-1],
  base.size = 16,
  theme.choice = "bw"
)

# Perform the longitudinal alpha diversity test for the peerj32 dataset without adjustment variables
alpha_test_results_peerj32_no_adj <- generate_alpha_change_per_time_test_long(
  data.obj = peerj32.obj,
  alpha.obj = NULL,
  alpha.name = c("shannon", "simpson", "observed_species", "chao1", "ace", "pielou"),
  time.var = "time",
  t0.level = unique(peerj32.obj$meta.dat$time)[1],
  ts.levels = unique(peerj32.obj$meta.dat$time)[-1],
  subject.var = "subject",
  group.var = "sex",
  adj.vars = NULL,
  alpha.change.func = "log fold change"
)
# Generate dot plots for the peerj32 dataset results without adjustment variables
generate_alpha_per_time_dotplot_long(
  data.obj = peerj32.obj,
  test.list = alpha_test_results_peerj32_no_adj,
  group.var = "sex",
  time.var = "time",
  t0.level = unique(peerj32.obj$meta.dat$time)[1],
  ts.levels = unique(peerj32.obj$meta.dat$time)[-1],
  base.size = 16,
  theme.choice = "minimal"
)

data("subset_T2D.obj")
# Perform the longitudinal alpha diversity test for the T2D dataset
alpha_test_results_T2D <- generate_alpha_change_per_time_test_long(
  data.obj = subset_T2D.obj,
  alpha.name = c("shannon", "simpson", "observed_species", "chao1", "ace", "pielou"),
  time.var = "visit_number",
  t0.level = unique(subset_T2D.obj$meta.dat$visit_number)[1],
  ts.levels = unique(subset_T2D.obj$meta.dat$visit_number)[-1],
  subject.var = "subject_id",
  group.var = "subject_race",
  adj.vars = c("sample_body_site"),
  alpha.change.func = "log fold change"
)
# Generate dot plots for the T2D dataset results
dot_plots_T2D <- generate_alpha_per_time_dotplot_long(
  data.obj = subset_T2D.obj,
  test.list = alpha_test_results_T2D,
  group.var = "subject_race",
  time.var = "visit_number",
  t0.level = unique(subset_T2D.obj$meta.dat$visit_number)[1],
  ts.levels = unique(subset_T2D.obj$meta.dat$visit_number)[-1],
  base.size = 16,
  theme.choice = "bw"
)

# Perform the longitudinal alpha diversity test for the T2D dataset without adjustment variables
alpha_test_results_T2D_no_adj <- generate_alpha_change_per_time_test_long(
  data.obj = subset_T2D.obj,
  alpha.name = c("shannon", "simpson", "observed_species", "chao1", "ace", "pielou"),
  time.var = "visit_number",
  t0.level = unique(subset_T2D.obj$meta.dat$visit_number)[1],
  ts.levels = unique(subset_T2D.obj$meta.dat$visit_number)[-1],
  subject.var = "subject_id",
  group.var = "subject_race",
  adj.vars = NULL,
  alpha.change.func = "log fold change"
)
# Generate dot plots for the T2D dataset results without adjustment variables
dot_plots_T2D_no_adj <- generate_alpha_per_time_dotplot_long(
  data.obj = subset_T2D.obj,
  test.list = alpha_test_results_T2D_no_adj,
  group.var = "subject_race",
  time.var = "visit_number",
  t0.level = unique(subset_T2D.obj$meta.dat$visit_number)[1],
  ts.levels = unique(subset_T2D.obj$meta.dat$visit_number)[-1],
  base.size = 16,
  theme.choice = "bw"
)
} # }