Skip to contents

PERMANOVA Test for Beta Diversity

Source: R/generate_beta_test_single.R
generate_beta_test_single.Rd

Performs PERMANOVA tests on beta diversity for cross-sectional microbiome data.

Usage

generate_beta_test_single(
  data.obj,
  dist.obj = NULL,
  time.var = NULL,
  t.level = NULL,
  group.var,
  adj.vars = NULL,
  dist.name = c("BC", "Jaccard")
)

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.

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.

t.level

Character string specifying the time level to subset to. If NULL, uses all data.

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

Value

A list containing the PERMANOVA results for each beta diversity index and an omnibus p-value. The list includes two elements: "p.tab" - a table of p-values for the PERMANOVA tests dplyr::across all indices, and "aov.tab" - a table containing detailed PERMANOVA results for each index. The p.tab and aov.tab tables include columns for the terms in the PERMANOVA model, the degrees of freedom, sums of squares, mean squares, F statistics, R-squared values, and p-values.

Examples

if (FALSE) { # \dontrun{

set.seed(123)
library(vegan)
data(peerj32.obj)

# Perform beta diversity tests using PERMANOVA
generate_beta_test_single(
  data.obj = peerj32.obj,
  dist.obj = NULL,
  time.var = "time",
  t.level = "2",
  group.var = "group",
  adj.vars = "sex",
  dist.name = c('BC', 'Jaccard')
)

# Perform beta diversity tests using PERMANOVA
generate_beta_test_single(
  data.obj = peerj32.obj,
  dist.obj = NULL,
  time.var = "time",
  t.level = NULL,
  group.var = "group",
  adj.vars = c("sex"),
  dist.name = c('BC', 'Jaccard')
)

# Perform beta diversity tests using PERMANOVA
generate_beta_test_single(
  data.obj = peerj32.obj,
  dist.obj = NULL,
  time.var = "time",
  t.level = "1",
  group.var = "group",
  adj.vars = c("sex"),
  dist.name = c('BC', 'Jaccard')
)

# Perform beta diversity tests using PERMANOVA
generate_beta_test_single(
  data.obj = peerj32.obj,
  dist.obj = NULL,
  time.var = "time",
  t.level = "2",
  group.var = "group",
  adj.vars = c("sex"),
  dist.name = c('BC', 'Jaccard')
)

data(ecam.obj)

# Perform beta diversity tests using PERMANOVA
generate_beta_test_single(
  data.obj = ecam.obj,
  dist.obj = NULL,
  time.var = "month",
  t.level = "0",
  group.var = "delivery",
  adj.vars = NULL,
  dist.name = c('BC', 'Jaccard')
)

# Perform beta diversity tests using PERMANOVA
generate_beta_test_single(
  data.obj = ecam.obj,
  dist.obj = NULL,
  time.var = "month",
  t.level = "0",
  group.var = "delivery",
  adj.vars = "diet",
  dist.name = c('BC', 'Jaccard')
)

dist.obj <- mStat_calculate_beta_diversity(ecam.obj, dist.name = c('BC', 'Jaccard'))
generate_beta_test_single(
  data.obj = ecam.obj,
  dist.obj = dist.obj,
  time.var = "month",
  t.level = "1",
  group.var = "delivery",
  adj.vars = "diet",
  dist.name = c('BC', 'Jaccard')
)
} # }