estimateDiversity: Estimate (alpha) diversity measures
In microbiome/mia: Microbiome analysis

estimateDiversity

R Documentation

Estimate (alpha) diversity measures

Description

Several functions for calculating (alpha) diversity indices, including the vegan package options and some others.

Usage

estimateDiversity(
  x,
  assay.type = "counts",
  assay_name = NULL,
  index = c("coverage", "fisher", "gini_simpson", "inverse_simpson",
    "log_modulo_skewness", "shannon"),
  name = index,
  ...
)

## S4 method for signature 'SummarizedExperiment'
estimateDiversity(
  x,
  assay.type = "counts",
  assay_name = NULL,
  index = c("coverage", "fisher", "gini_simpson", "inverse_simpson",
    "log_modulo_skewness", "shannon"),
  name = index,
  ...,
  BPPARAM = SerialParam()
)

## S4 method for signature 'TreeSummarizedExperiment'
estimateDiversity(
  x,
  assay.type = "counts",
  assay_name = NULL,
  index = c("coverage", "faith", "fisher", "gini_simpson", "inverse_simpson",
    "log_modulo_skewness", "shannon"),
  name = index,
  tree_name = "phylo",
  ...,
  BPPARAM = SerialParam()
)

estimateFaith(
  x,
  tree = "missing",
  assay.type = "counts",
  assay_name = NULL,
  name = "faith",
  ...
)

## S4 method for signature 'SummarizedExperiment,phylo'
estimateFaith(
  x,
  tree,
  assay.type = "counts",
  assay_name = NULL,
  name = "faith",
  node_lab = NULL,
  ...
)

## S4 method for signature 'TreeSummarizedExperiment,missing'
estimateFaith(
  x,
  assay.type = "counts",
  assay_name = NULL,
  name = "faith",
  tree_name = "phylo",
  ...
)

Arguments

`x`	a `SummarizedExperiment` object or `TreeSummarizedExperiment`. The latter is recommended for microbiome data sets and tree-based alpha diversity indices.
`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.)
`index`	a `character` vector, specifying the diversity measures to be calculated.
`name`	a name for the column(s) of the colData the results should be stored in. By default this will use the original names of the calculated indices.
`...`	optional arguments: threshold A numeric value in the unit interval, determining the threshold for coverage index. By default, `threshold` is 0.9. quantile Arithmetic abundance classes are evenly cut up to to this quantile of the data. The assumption is that abundances higher than this are not common, and they are classified in their own group. By default, `quantile` is 0.5. num_of_classes The number of arithmetic abundance classes from zero to the quantile cutoff indicated by `quantile`. By default, `num_of_classes` is 50. only.tips A boolean value specifying whether to remove internal nodes when Faith's index is calculated. When `only.tips=TRUE`, those rows that are not tips of tree are removed. (By default: `only.tips=FALSE`)
`BPPARAM`	A `BiocParallelParam` object specifying whether calculation of estimates should be parallelized.
`tree_name`	a single `character` value for specifying which rowTree will be used to calculate faith index. (By default: `tree_name = "phylo"`)
`tree`	A phylogenetic tree that is used to calculate 'faith' index. If `x` is a `TreeSummarizedExperiment`, `rowTree(x)` is used by default.
`node_lab`	NULL or a character vector specifying the links between rows and node labels of `tree`. If a certain row is not linked with the tree, missing instance should be noted as NA. When NULL, all the rownames should be found from the tree. (By default: `node_lab = NULL`)

Details

The available indices include the ‘Coverage’, ‘Faith's phylogenetic diversity’, ‘Fisher alpha’, ‘Gini-Simpson’, ‘Inverse Simpson’, ‘log-modulo skewness’, and ‘Shannon’ indices. See details for more information and references.

Alpha diversity is a joint quantity that combines elements or community richness and evenness. Diversity increases, in general, when species richness or evenness increase.

By default, this function returns all indices.

'coverage' Number of species needed to cover a given fraction of the ecosystem (50 percent by default). Tune this with the threshold argument.
'faith' Faith's phylogenetic alpha diversity index measures how long the taxonomic distance is between taxa that are present in the sample. Larger values represent higher diversity. Using this index requires rowTree. (Faith 1992)

If the data includes features that are not in tree's tips but in internal nodes, there are two options. First, you can keep those features, and prune the tree to match features so that each tip can be found from the features. Other option is to remove all features that are not tips. (See only.tips parameter)
'fisher' Fisher's alpha; as implemented in vegan::fisher.alpha. (Fisher et al. 1943)
'gini_simpson' Gini-Simpson diversity i.e. 1 - lambda, where lambda is the Simpson index, calculated as the sum of squared relative abundances. This corresponds to the diversity index 'simpson' in vegan::diversity. This is also called Gibbs–Martin, or Blau index in sociology, psychology and management studies. The Gini-Simpson index (1-lambda) should not be confused with Simpson's dominance (lambda), Gini index, or inverse Simpson index (1/lambda).
'inverse_simpson' Inverse Simpson diversity: 1/lambda where lambda=sum(p^2) and p refers to relative abundances. This corresponds to the diversity index 'invsimpson' in vegan::diversity. Don't confuse this with the closely related Gini-Simpson index
'log_modulo_skewness' The rarity index characterizes the concentration of species at low abundance. Here, we use the skewness of the frequency distribution of arithmetic abundance classes (see Magurran & McGill 2011). These are typically right-skewed; to avoid taking log of occasional negative skews, we follow Locey & Lennon (2016) and use the log-modulo transformation that adds a value of one to each measure of skewness to allow logarithmization.
'shannon' Shannon diversity (entropy).

Value

x with additional colData named *name*

Author(s)

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

References

Beisel J-N. et al. (2003) A Comparative Analysis of Diversity Index Sensitivity. Internal Rev. Hydrobiol. 88(1):3-15. https://portais.ufg.br/up/202/o/2003-comparative_evennes_index.pdf

Bulla L. (1994) An index of diversity and its associated diversity measure. Oikos 70:167–171

Faith D.P. (1992) Conservation evaluation and phylogenetic diversity. Biological Conservation 61(1):1-10.

Fisher R.A., Corbet, A.S. & Williams, C.B. (1943) The relation between the number of species and the number of individuals in a random sample of animal population. Journal of Animal Ecology 12, 42-58.

Locey K.J. & Lennon J.T. (2016) Scaling laws predict global microbial diversity. PNAS 113(21):5970-5975.

Magurran A.E., McGill BJ, eds (2011) Biological Diversity: Frontiers in Measurement and Assessment. (Oxford Univ Press, Oxford), Vol 12.

Smith B. & Wilson JB. (1996) A Consumer's Guide to Diversity Indices. Oikos 76(1):70-82.

Examples

data(GlobalPatterns)
tse <- GlobalPatterns

# All index names as known by the function
index <- c("shannon","gini_simpson","inverse_simpson", "coverage", "fisher", 
"faith",  "log_modulo_skewness")

# Corresponding polished names
name <- c("Shannon","GiniSimpson","InverseSimpson", "Coverage", "Fisher", 
"Faith",  "LogModSkewness")

# Calculate diversities
tse <- estimateDiversity(tse, index = index)

# The colData contains the indices with their code names by default
colData(tse)[, index]

# Removing indices
colData(tse)[, index] <- NULL

# 'threshold' can be used to determine threshold for 'coverage' index
tse <- estimateDiversity(tse, index = "coverage", threshold = 0.75)
# 'quantile' and 'num_of_classes' can be used when
# 'log_modulo_skewness' is calculated
tse <- estimateDiversity(tse, index = "log_modulo_skewness",
       quantile = 0.75, num_of_classes = 100)

# It is recommended to specify also the final names used in the output.
tse <- estimateDiversity(tse,
  index = c("shannon", "gini_simpson", "inverse_simpson", "coverage",
               "fisher", "faith", "log_modulo_skewness"),
   name = c("Shannon", "GiniSimpson",  "InverseSimpson",  "Coverage",
               "Fisher", "Faith", "LogModSkewness"))

# The colData contains the indices by their new names provided by the user
colData(tse)[, name]

# Compare the indices visually
pairs(colData(tse)[, name])

# Plotting the diversities - use the selected names
library(scater)
plotColData(tse, "Shannon")
# ... by sample type
plotColData(tse, "Shannon", "SampleType")

# combining different plots
library(patchwork)
plot_index <- c("Shannon","GiniSimpson")
plots <- lapply(plot_index,
               plotColData,
               object = tse,
               x = "SampleType",
               colour_by = "SampleType")
plots <- lapply(plots,"+",
   theme(axis.text.x = element_text(angle=45,hjust=1)))
names(plots) <- plot_index
plots$Shannon + plots$GiniSimpson + plot_layout(guides = "collect")

microbiome/mia documentation built on April 27, 2024, 4:04 a.m.