Skip to contents

Beta Diversity Volatility Test for Longitudinal Data

Source: R/generate_beta_volatility_test_long.R
generate_beta_volatility_test_long.Rd

Tests association between beta diversity volatility and group variable for longitudinal microbiome data.

Usage

generate_beta_volatility_test_long(
  data.obj,
  dist.obj = NULL,
  subject.var,
  time.var,
  group.var,
  adj.vars = NULL,
  dist.name = c("BC"),
  ...
)

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.

dist.obj

A list of pre-calculated distance matrices. If NULL and distances are needed, they will be calculated automatically. List names should match dist.name (e.g., "BC" for Bray-Curtis). See mStat_calculate_beta_diversity.

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

Required. Character string specifying the grouping variable in metadata.

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.

dist.name

Character vector specifying which distance metrics to use. Options depend on available methods:

  • "BC": Bray-Curtis dissimilarity

  • "Jaccard": Jaccard distance

  • "UniFrac": Unweighted UniFrac (requires tree)

  • "GUniFrac": Generalized UniFrac (requires tree)

  • "WUniFrac": Weighted UniFrac (requires tree)

  • "JS": Jensen-Shannon divergence

...

Additional arguments passed to internal functions.

Value

A list containing the result of the volatility test for each specified beta diversity index. Each element in the list is a tibble with the coefficients extracted from the linear model fitted for each distance, and an ANOVA table if the group variable is multi-categorical.

Details

The function starts by validating the input data, processing the time variable, and calculating the beta diversity if necessary. Adjustments are made based on the provided adjusting variables. The volatility of the beta diversity is computed for each subject, and linear models are fitted to test the association between volatility and the specified group variable. The coefficients and ANOVA results are extracted and returned for each beta diversity index specified.

Note

A warning message will be displayed to ensure that the time variable is coded as numeric. Non-numeric coding may lead to issues in the volatility test computation.

See also

mStat_calculate_beta_diversity, mStat_calculate_adjusted_distance

Examples

if (FALSE) { # \dontrun{
data(ecam.obj)
generate_beta_volatility_test_long(
  data.obj = ecam.obj,
  dist.obj = NULL,
  subject.var = "studyid",
  time.var = "month_num",
  t0.level = NULL,
  ts.levels = NULL,
  group.var = "diet",
  adj.vars = NULL,
  dist.name = c("BC", "Jaccard")
)

data(subset_T2D.obj)
generate_beta_volatility_test_long(
  data.obj = subset_T2D.obj,
  dist.obj = NULL,
  subject.var = "subject_id",
  time.var = "visit_number_num",
  t0.level = NULL,
  ts.levels = NULL,
  group.var = "subject_race",
  adj.vars = NULL,
  dist.name = c("BC", "Jaccard")
)
} # }