Alpha Diversity Change Test (Paired)

Performs paired tests comparing alpha diversity changes between two time points, using linear models with optional group comparisons and covariate adjustment.

Usage

generate_alpha_change_test_pair(
  data.obj,
  alpha.obj = NULL,
  alpha.name = NULL,
  depth = NULL,
  subject.var,
  time.var,
  group.var,
  adj.vars = NULL,
  change.base,
  alpha.change.func = "log fold change"
)

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.

alpha.obj

A list containing pre-calculated alpha diversity indices. If NULL and alpha diversity is needed, it will be calculated automatically. Names should match the alpha.name parameter (e.g., "shannon", "simpson"). See mStat_calculate_alpha_diversity.

alpha.name

Character vector specifying which alpha diversity indices to analyze. Options include:

• "shannon": Shannon diversity index

• "simpson": Simpson diversity index

• "observed_species": Observed species richness

• "chao1": Chao1 richness estimator

• "ace": ACE richness estimator

• "pielou": Pielou's evenness

• "faith_pd": Faith's phylogenetic diversity (requires a tree)

depth

Numeric value or NULL. Rarefaction depth for rarefaction workflows. If NULL, uses the minimum sample depth.

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. Supports character/factor labels (e.g., "baseline", "week4") and numeric values. Some trend/volatility methods require numeric or coercible-to-numeric time values.

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.

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.

change.base

The baseline time point for calculating changes. 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. Options include 'log fold change', 'absolute change', or a custom function taking two arguments (t, 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).

Examples

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

# Example 1: Basic paired comparison by group
generate_alpha_change_test_pair(
  data.obj = peerj32.obj,
  alpha.obj = NULL,
  alpha.name = c("shannon"),
  subject.var = "subject",
  time.var = "time",
  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 a renamed time variable with no additional adjustment
generate_alpha_change_test_pair(
  data.obj = peerj32.obj,
  alpha.obj = NULL,
  alpha.name = c("shannon"),
  subject.var = "subject",
  time.var = "Day",
  group.var = "sex",
  adj.vars = NULL,
  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,
  alpha.name = c("shannon"),
  subject.var = "MouseID",
  time.var = "Antibiotic",
  group.var = "Sex",
  adj.vars = NULL,
  change.base = "Baseline",
  alpha.change.func = "log fold change"
)

} # }