Generate Beta Diversity Trend Test for Longitudinal Data — generate_beta_trend_test

The function `generate_beta_trend_test_long` performs a linear mixed effects model to test the longitudinal trend in beta diversity. It models the distance matrix as the response, with time as a fixed effect and subject as a random effect. An optional grouping variable can be included as an interaction with time. Covariates for adjustment can also be added to the model. The time variable should be numeric, and the function coerces it as needed. The linear mixed model is fitted using lmer, and the estimated coefficients are extracted and returned, representing the trends over time and differences between groups.

Usage

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

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.
dist.obj: Distance matrix between samples, usually calculated using mStat_calculate_beta_diversity function. If NULL, beta diversity will be automatically computed from data.obj using mStat_calculate_beta_diversity.
subject.var: The variable name in metadata that represents the subject identifiers. Should match the subject identifiers used when calculating distance matrix.
time.var: The variable name in metadata that represents the time points. Should be a numeric vector coded as continuous values. The function will try to coerce to numeric if needed.
group.var: (Optional) The variable name in metadata that represents the grouping factor of interest. Default is NULL.
adj.vars: (Optional) A character vector of variable names in metadata to be used for adjustment in the model. Default is NULL.
dist.name: A character vector specifying which beta diversity indices to calculate. Default is "BC" (Bray-Curtis). Supported indices include "BC", "Jaccard", "UniFrac", "GUniFrac", "WUniFrac", and "JS".
...: (Optional) Additional arguments to pass to internal functions.

Value

A list containing the result of the trend test for each specified beta diversity index. The result includes a tibble with the coefficients extracted from the mixed-effects model fitted for each distance.

Details

The function starts by validating the input data, followed by processing the time variable and calculating the beta diversity if necessary. Adjustments are made based on the provided adjusting variables, and the mixed-effects model is fitted to the long-format data. The coefficients of the model 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 trend test computation.

Examples

if (FALSE) { # \dontrun{
data(ecam.obj)
generate_beta_trend_test_long(
  data.obj = ecam.obj,
  dist.obj = NULL,
  subject.var = "studyid",
  time.var = "month",
  group.var = "diet",
  adj.vars = c("antiexposedall","delivery"),
  dist.name = c("BC", "Jaccard")
  )

generate_beta_trend_test_long(
  data.obj = ecam.obj,
  dist.obj = NULL,
  subject.var = "studyid",
  time.var = "month",
  group.var = NULL,
  adj.vars = NULL,
  dist.name = c("BC", "Jaccard")
  )

data(subset_T2D.obj)
generate_beta_trend_test_long(
  data.obj = subset_T2D.obj,
  dist.obj = NULL,
  subject.var = "subject_id",
  time.var = "visit_number",
  group.var = "subject_race",
  adj.vars = c("subject_gender","sample_body_site"),
  dist.name = c("BC", "Jaccard")
)

generate_beta_trend_test_long(
  data.obj = subset_T2D.obj,
  dist.obj = NULL,
  subject.var = "subject_id",
  time.var = "visit_number",
  group.var = NULL,
  adj.vars = NULL,
  dist.name = c("BC", "Jaccard")
)
} # }