Skip to contents

Trend Test on Principal Coordinates for Longitudinal Data

Source: R/generate_beta_pc_trend_test_long.R
generate_beta_pc_trend_test_long.Rd

Performs linear trend tests on PC axes of beta diversity over time using mixed effects models.

Usage

generate_beta_pc_trend_test_long(
  data.obj = NULL,
  dist.obj = NULL,
  pc.obj = NULL,
  pc.ind = c(1, 2),
  subject.var,
  time.var,
  group.var = NULL,
  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.

pc.obj

A list containing dimension reduction results from mStat_calculate_PC. If NULL, PCoA is performed automatically.

pc.ind

Numeric vector specifying which PC axes to test. Default c(1, 2).

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.

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 lmer().

Value

A nested list by distance > PC. Each element contains:

  • coef: Data frame of coefficients from mixed effects model.

  • model: Fitted lmer model object.

Details

This function allows performing linear trend tests on PCs of beta diversity distances over time, across groups, with adjustments.

It checks for pre-calculated distances and PCs, generating them from data if needed. Sufficient PCs should be calculated to cover indices specified.

For each distance, PCs are extracted for the selected indices. The metadata is joined and formatted for mixed effects modeling with time as numeric.

The model formula is created using the response, time, group, and subject variables. Mixed effects models are fitted with lmer() and coefficients extracted.

See also

mStat_calculate_beta_diversity to generate distance matrices.

mStat_calculate_PC to generate PCs from distances.

Examples

if (FALSE) { # \dontrun{
library(vegan)
data("ecam.obj")
generate_beta_pc_trend_test_long(
  data.obj = ecam.obj,
  dist.obj = NULL,
  pc.obj = NULL,
  pc.ind = c(1, 2),
  subject.var = "studyid",
  time.var = "month",
  group.var = "diet",
  adj.vars = "delivery",
  dist.name = c('BC')
)

data("subset_T2D.obj")
generate_beta_pc_trend_test_long(
  data.obj = subset_T2D.obj,
  dist.obj = NULL,
  pc.obj = NULL,
  pc.ind = c(1, 2),
  subject.var = "subject_id",
  time.var = "visit_number_num",
  group.var = "subject_race",
  adj.vars = "subject_gender",
  dist.name = c('BC')
)
} # }