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.

- '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. (Faith 1992)

- '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.

### See Also

`plotColData`

- `estimateRichness`

- `estimateEvenness`

- `estimateDominance`

- `diversity`

- `estimateR`

### 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.2.7 Index]