addDivergence: Estimate divergence

In FelixErnst/mia: Microbiome analysis

Estimate divergence

Description

Estimate divergence against a given reference sample.

Usage

addDivergence(
  x,
  assay.type = assay_name,
  assay_name = "counts",
  name = "divergence",
  reference = "median",
  FUN = vegan::vegdist,
  method = "bray",
  ...
)

## S4 method for signature 'SummarizedExperiment'
addDivergence(
  x,
  assay.type = assay_name,
  assay_name = "counts",
  name = "divergence",
  reference = "median",
  FUN = vegan::vegdist,
  method = "bray",
  ...
)

Arguments

x	a SummarizedExperiment object.
assay.type	the name of the assay used for calculation of the sample-wise estimates.
assay_name	a single character value for specifying which assay to use for calculation. (Please use assay.type instead. At some point assay_name will be disabled.)
name	a name for the column of the colData the results should be stored in. By default, name is "divergence".
reference	a numeric vector that has length equal to number of features, or a non-empty character value; either 'median' or 'mean'. reference specifies the reference that is used to calculate divergence. by default, reference is "median".
FUN	a function for distance calculation. The function must expect the input matrix as its first argument. With rows as samples and columns as features. By default, FUN is vegan::vegdist.
method	a method that is used to calculate the distance. Method is passed to the function that is specified by FUN. By default, method is "bray".
...	optional arguments

Details

Microbiota divergence (heterogeneity / spread) within a given sample set can be quantified by the average sample dissimilarity or beta diversity with respect to a given reference sample.

This measure is sensitive to sample size. Subsampling or bootstrapping can be applied to equalize sample sizes between comparisons.

Value

x with additional colData named *name*

Author(s)

Leo Lahti and Tuomas Borman. Contact: microbiome.github.io

See Also

plotColData

• estimateRichness

• estimateEvenness

• estimateDominance

Examples

data(GlobalPatterns)
tse <- GlobalPatterns

# By default, reference is median of all samples. The name of column where results
# is "divergence" by default, but it can be specified. 
tse <- addDivergence(tse)

# The method that are used to calculate distance in divergence and 
# reference can be specified. Here, euclidean distance and dist function from 
# stats package are used. Reference is the first sample.
tse <- addDivergence(tse, name = "divergence_first_sample", 
                          reference = assays(tse)$counts[,1], 
                          FUN = stats::dist, method = "euclidean")

# Reference can also be median or mean of all samples. 
# By default, divergence is calculated by using median. Here, mean is used.
tse <- addDivergence(tse, name = "divergence_average", reference = "mean")

# All three divergence results are stored in colData.
colData(tse)

FelixErnst/mia documentation built on May 15, 2024, 6:31 a.m.