Alpha Diversity Trend Test (Longitudinal)

Tests for temporal trends in alpha diversity using linear mixed-effects models with a numeric time variable.

Usage

generate_alpha_trend_test_long(
  data.obj,
  alpha.obj = NULL,
  alpha.name = c("shannon", "observed_species"),
  depth = NULL,
  time.var,
  subject.var,
  group.var = NULL,
  adj.vars = NULL
)

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

depth

Numeric value or NULL. Rarefaction depth for diversity calculations. If NULL, uses minimum sample depth or no rarefaction.

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.

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.

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.

Value

A list object containing the results of the trend test for each alpha diversity index specified in `alpha.name`. Each element of the list contains a summary table of the trend test results for a specific alpha diversity index.

Examples

if (FALSE) { # \dontrun{
# Load example data
data("subset_T2D.obj")

# Example 1: Test trend for multiple alpha indices with group and no adjustment
result1 <- generate_alpha_trend_test_long(
  data.obj = subset_T2D.obj,
  alpha.name = c("shannon", "observed_species"),
  time.var = "visit_number_num",
  subject.var = "subject_id",
  group.var = "subject_race"
)

# Example 2: Test trend for multiple alpha indices with group and adjustment for one covariate
result2 <- generate_alpha_trend_test_long(
  data.obj = subset_T2D.obj,
  alpha.name = c("shannon", "observed_species"),
  time.var = "visit_number_num",
  subject.var = "subject_id",
  group.var = "subject_race",
  adj.vars = "subject_gender"
)

# Example 3: Test trend for multiple alpha indices with group and adjustment for multiple covariates
result3 <- generate_alpha_trend_test_long(
  data.obj = subset_T2D.obj,
  alpha.name = c("shannon", "observed_species"),
  time.var = "visit_number_num",
  subject.var = "subject_id",
  group.var = "subject_race",
  adj.vars = c("subject_gender", "sample_body_site")
)

# Example 4: Test trend for multiple alpha indices without group
result4 <- generate_alpha_trend_test_long(
  data.obj = subset_T2D.obj,
  alpha.name = c("shannon", "observed_species"),
  time.var = "visit_number_num",
  subject.var = "subject_id"
)

# Example 5: Test trend for a single alpha index with group
result5 <- generate_alpha_trend_test_long(
  data.obj = subset_T2D.obj,
  alpha.name = "chao1",
  time.var = "visit_number_num",
  subject.var = "subject_id",
  group.var = "subject_race"
)

# Example 6: Test trend using pre-calculated alpha diversity
alpha.obj <- mStat_calculate_alpha_diversity(subset_T2D.obj$feature.tab,
c("shannon", "observed_species"))
result6 <- generate_alpha_trend_test_long(
  data.obj = subset_T2D.obj,
  alpha.obj = alpha.obj,
  time.var = "visit_number_num",
  subject.var = "subject_id",
  group.var = "subject_race"
)
} # }