Skip to contents

Generate Beta PC Volatility Test in Long Format

Source: R/generate_beta_pc_volatility_test_long.R
generate_beta_pc_volatility_test_long.Rd

This function computes the volatility test for principal coordinates (PC) of beta diversity. It allows for a variety of distance measures and optional adjustments. The function relies on a numeric time variable.

Usage

generate_beta_pc_volatility_test_long(
  data.obj,
  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 list object in a format specific to MicrobiomeStat, containing components such as feature.tab (matrix), feature.ann (matrix), meta.dat (data.frame), tree, and feature.agg.list (list). If dist.obj is provided, data.obj is not required.

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.

pc.obj

A list containing the results of dimension reduction/Principal Component Analysis. This should be the output from functions like mStat_calculate_PC, containing the PC coordinates and other metadata. If NULL (default), dimension reduction will be automatically performed using metric multidimensional scaling (MDS) via mStat_calculate_PC. The pc.obj list structure should contain:

points

A matrix with samples as rows and PCs as columns containing the coordinates.

eig

Eigenvalues for each PC dimension.

vectors

Loadings vectors for features onto each PC.

Other metadata

like method, dist.name, etc.

See mStat_calculate_PC function for details on output format.

pc.ind

Numeric vector indicating which principal coordinate (PC) axes to use for volatility test, e.g. c(1,2) for PC1 and PC2. Defaults to c(1,2).

subject.var

Character string specifying the column in metadata containing unique subject IDs. This should uniquely identify each subject in the study. Required to compute volatility within subjects.

time.var

Character string specifying the column in metadata containing the time variable. This should be numeric with successive time points for each subject. Required to compute volatility over time.

group.var

(Optional) Character string specifying the column in metadata containing a grouping variable. This grouping variable will be used to test for differences in volatility between groups. Can be left NULL.

adj.vars

(Optional) Character vector specifying columns in metadata containing variables to adjust for in the volatility models. Can be left NULL.

dist.name

A character vector specifying which beta diversity indices to calculate. Supported indices are "BC" (Bray-Curtis), "Jaccard", "UniFrac" (unweighted UniFrac), "GUniFrac" (generalized UniFrac), "WUniFrac" (weighted UniFrac), and "JS" (Jensen-Shannon divergence). If a name is provided but the corresponding object does not exist within dist.obj, it will be computed internally. If the specific index is not supported, an error message will be returned. Default is c('BC', 'Jaccard').

...

(Optional) Additional arguments to pass to internal functions.

Value

A list of results for each distance measure and selected Principal Coordinate, including coefficients from the mixed-effects models.

Examples

if (FALSE) { # \dontrun{
library(vegan)
data(ecam.obj)
generate_beta_pc_volatility_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 = NULL,
  dist.name = c('BC')
)
} # }