Compare alpha diversity between time points — generate_alpha_change_test

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

Usage

generate_alpha_change_test_pair(
  data.obj,
  alpha.obj = NULL,
  alpha.name = NULL,
  depth = NULL,
  time.var,
  subject.var,
  group.var,
  adj.vars = NULL,
  change.base,
  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, 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.

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.

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.

change.base

The name of the baseline time point for calculating changes in alpha diversity. If NULL, the first unique time point in the data will be used.

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.

Value

A list of tables, one for each alpha diversity metric, summarizing the results of the statistical tests. Each table contains the following columns: Term (the name of the variable in the model), Estimate (the estimated coefficient), Std.Error (the standard error of the coefficient), Statistic (the t or F statistic), P.Value (the p-value of the test).

Details

For each alpha diversity metric, the difference between the two time points is calculated for each subject. The difference is used as the response variable in a linear model, with grouping and adjustment variables as predictors.

The linear model coefficients are extracted into a results table. If the grouping variable has multiple levels, ANOVA is performed to test for overall significance.

Options are provided to customize the alpha diversity difference calculation (e.g. log-fold change) and adjust for covariates.

In summary, this provides a flexible paired test for analyzing changes in alpha diversity over time, accounting for groups and covariates.

This function performs the following statistical tests:

- For each alpha diversity metric, a linear model is fitted with the difference in alpha diversity between two time points as the response, and the grouping variable and any adjustment variables as predictors. The linear model coefficients are extracted and formatted into a results table.

- If the grouping variable has more than 2 levels, ANOVA is performed on the linear model to obtain the overall significance of the grouping variable. The ANOVA results are also formatted into the results table.

So in summary, the function provides a paired test for the change in alpha diversity between two time points, with options to adjust for covariates and test for differences between groups. The output contains coefficient tables summarizing the results of the linear models and ANOVA tests.

Examples

if (FALSE) { # \dontrun{
library(vegan)
data(peerj32.obj)

# Example 1: Using both group.var and adj.vars
generate_alpha_change_test_pair(
  data.obj = peerj32.obj,
  alpha.obj = NULL,
  time.var = "time",
  alpha.name = c("shannon"),
  subject.var = "subject",
  group.var = "sex",
  adj.vars = NULL,
  change.base = "2",
  alpha.change.func = "log fold change"
)

# Rename the time variable in peerj32.obj's metadata
peerj32.obj$meta.dat <- peerj32.obj$meta.dat %>%
  dplyr::rename(Day = time)

# Example 2: Using group.var and adj.vars with a renamed time variable
generate_alpha_change_test_pair(
  data.obj = peerj32.obj,
  alpha.obj = NULL,
  time.var = "Day",
  alpha.name = c("shannon"),
  subject.var = "subject",
  group.var = "sex",
  adj.vars = c("group"),
  change.base = "2",
  alpha.change.func = "log fold change"
)

data("subset_pairs.obj")

# Example 3: With group.var and without adj.vars
generate_alpha_change_test_pair(
  data.obj = subset_pairs.obj,
  alpha.obj = NULL,
  time.var = "Antibiotic",
  alpha.name = c("shannon"),
  subject.var = "MouseID",
  group.var = "Sex",
  adj.vars = NULL,
  change.base = "Baseline",
  alpha.change.func = "log fold change"
)

} # }