Calculate various beta diversity indices

This function calculates a variety of beta diversity indices based on the input data, such as Bray-Curtis (BC), Jaccard, unweighted UniFrac (UniFrac), generalized UniFrac (GUniFrac), weighted UniFrac (WUniFrac), and Jensen-Shannon divergence (JS).

Usage

mStat_calculate_beta_diversity(
  data.obj,
  dist.name = c("BC", "Jaccard", "UniFrac", "GUniFrac", "WUniFrac", "JS")
)

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.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. "BC" (Bray-Curtis), "Jaccard", "UniFrac" (unweighted UniFrac), "GUniFrac" (generalized UniFrac), "WUniFrac" (weighted UniFrac), and "JS" (Jensen-Shannon divergence).

Value

A list containing the calculated beta diversity indices. The indices are named with the abbreviation.

Examples

if (FALSE) { # \dontrun{
library(vegan) # Used for community ecology analyses
library(GUniFrac) # For generalized UniFrac distances
# library(phyloseq) # For handling and analyzing phylogenetic sequencing data
# Load example data
# data(GlobalPatterns) # An example dataset from the phyloseq package
# Convert the phyloseq object to a MicrobiomeStat data object
# This step is crucial for making the dataset compatible with MicrobiomeStat functions
# GlobalPatterns.obj <- mStat_convert_phyloseq_to_data_obj(GlobalPatterns)
# Calculate various beta diversity indices
# Beta diversity measures the difference in microbial communities across samples
# Bray-Curtis dissimilarity (BC)
# A commonly used measure of dissimilarity based on counts
# dist.obj <- mStat_calculate_beta_diversity(GlobalPatterns.obj, dist.name = c('BC'))
# Jaccard index
# A measure based on presence/absence, useful for binary data
# dist.obj <- mStat_calculate_beta_diversity(GlobalPatterns.obj, dist.name = c("Jaccard"))
# UniFrac distance
# A phylogenetic measure of community dissimilarity
# Requires a phylogenetic tree as part of the input
# dist.obj <- mStat_calculate_beta_diversity(GlobalPatterns.obj, dist.name = c('UniFrac'))
# Weighted UniFrac distance (WUniFrac)
# A variation of UniFrac that accounts for relative abundance
# Also requires a phylogenetic tree
# dist.obj <- mStat_calculate_beta_diversity(GlobalPatterns.obj, dist.name = c('WUniFrac'))
# Jensen-Shannon divergence (JS)
# A symmetric and smoothed version of the Kullback-Leibler divergence
# Useful for comparing probability distributions
# dist.obj <- mStat_calculate_beta_diversity(GlobalPatterns.obj, dist.name = c('JS'))
} # }