estimateDiversity {mia}R Documentation

Estimate diversity measures

Description

Several functions for calculating diversity indices are available via wrapper functions. Some of them are implemented via the vegan package.

Usage

estimateDiversity(
  x,
  abund_values = "counts",
  index = c("coverage", "fisher", "gini_simpson", "inverse_simpson",
    "log_modulo_skewness", "shannon"),
  name = index,
  ...
)

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

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

estimateFaith(
  x,
  tree = "missing",
  abund_values = "counts",
  name = "faith",
  ...
)

## S4 method for signature 'SummarizedExperiment,phylo'
estimateFaith(
  x,
  tree = "missing",
  abund_values = "counts",
  name = "faith",
  ...
)

## S4 method for signature 'TreeSummarizedExperiment,missing'
estimateFaith(
  x,
  tree = "missing",
  abund_values = "counts",
  name = "faith",
  ...
)

Arguments

x

a SummarizedExperiment object

abund_values

the name of the assay used for calculation of the sample-wise estimates.

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.

...

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.

BPPARAM

A BiocParallelParam object specifying whether calculation of estimates should be parallelized.

tree

A phylogenetic tree that is used to calculate 'faith' index. If x is a TreeSummarizedExperiment, rowTree(x) is used by default.

Details

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

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.

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.

See Also

plotColData

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")
## Not run: 
# 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")

## End(Not run)

[Package mia version 1.1.13 Index]