Alphadiversity.Rmd

---
title: "Alpha diversity"
author: "Leo Lahti, Sudarshan Shetty et al."
bibliography: 
- bibliography.bib
output:
  BiocStyle::html_document:
    number_sections: no
    toc: yes
    toc_depth: 4
    toc_float: true
    self_contained: true
    thumbnails: true
    lightbox: true
    gallery: true
    use_bookdown: false
    highlight: haddock    
---
<!--
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{microbiome tutorial - diversity}
  %\usepackage[utf8]{inputenc}
  %\VignetteEncoding{UTF-8}  
-->


## Global Ecosystem State Variables 

This page provides examples for analysing alpha diversity. See a separate page for [beta diversity](https://microbiome.github.io/tutorials/Betadiversity.html).



Load example data:

```{r divdata, warning=FALSE, message=FALSE, fig.height=3, fig.width=5}
library(microbiome)
library(knitr)
data(dietswap)
pseq <- dietswap
```


## Global indicators

A comprehensive list of global indicators of the ecosystem state can be obtained as follows. This includes various measures of richness, evenness, diversity, dominance, and rarity with default parameters. See the individual functions for more options regarding parameter tuning.

```{r alpha, warning=FALSE, message=FALSE, fig.height=3, fig.width=5, results="asis"}
tab <-microbiome::alpha(pseq, index = "all")
kable(head(tab))
```


## Alpha diversity

This returns a table with selected diversity indicators. See a separate page on [Beta diversity](Betadiversity.html).

```{r alpha2, warning=FALSE, message=FALSE, fig.height=3, fig.width=5, results="asis"}
tab <-microbiome::alpha(pseq, index = "all")
kable(head(tab))
```


## Richness

This returns observed richness with given detection threshold(s).

```{r divest, warning=FALSE, message=FALSE, fig.height=3, fig.width=5}
tab <- richness(pseq)
kable(head(tab))
```


## Dominance 

The dominance index refers to the abundance of the most abundant species. Various dominance indices are available (see the function help for a list of options).

```{r dominance, warning=FALSE, message=FALSE}
# Absolute abundances for the single most abundant taxa in each sample
tab <- dominance(pseq, index = "all")
kable(head(tab))
```

We also have a function to list the dominating (most abundant) taxa in each sample.


```{r dominant, warning=FALSE, message=FALSE, results="hide"}
dominant(pseq)
```



## Rarity and low abundance

The rarity indices quantify the concentration of rare or low abundance taxa. Various rarity indices are available (see the function help for a list of options).

```{r lowab, warning=FALSE, message=FALSE}
tab <- rarity(pseq, index = "all")
kable(head(tab))
```



## Coverage

The coverage index gives the number of groups needed to have a given proportion of the ecosystem occupied (by default 0.5 ie 50%).

```{r coverage, warning=FALSE, message=FALSE, eval=FALSE}
tab <- coverage(pseq, threshold = 0.5)
kable(head(tab))
```


## Core abundance

The core_abundance function refers to the relative proportion of the core species. Non-core abundance provides the complement (1-x; see rare_abundance).

```{r divest5, warning=FALSE, message=FALSE}
tab <- core_abundance(pseq, detection = .1/100, prevalence = 50/100)
```


## Gini index

Gini index is a common measure for inequality in economical income. The inverse gini index (1/x) can also be used as a community diversity measure.

```{r divest6, warning=FALSE, message=FALSE}
tab <- inequality(pseq)
```


## Evenness

Various evenness measures are also available.

```{r evenness, warning=FALSE, message=FALSE}
tab <- evenness(pseq, "all")
kable(head(tab))
```

## Visualization  

To visualize diversity measures, the package provides a simple wrapper around ggplot2. Currently onnly one measure can be visualized at a time.    

```{r fig.height=4, fig.width=6}
p.shannon <- boxplot_alpha(pseq, 
                           index = "shannon",
                           x_var = "sex",
                           fill.colors = c(female="cyan4", male="deeppink4"))

p.shannon <- p.shannon + theme_minimal() + 
  labs(x="Sex", y="Shannon diversity") +
  theme(axis.text = element_text(size=12),
        axis.title = element_text(size=16),
        legend.text = element_text(size=12),
        legend.title = element_text(size=16))
p.shannon
```


## Testing differences in alpha diversity

We recommend the non-parametric [Kolmogorov-Smirnov test](https://www.rdocumentation.org/packages/dgof/versions/1.2/topics/ks.test) for two-group comparisons when there are no relevant covariates.

```{r kstest, warning=FALSE, message=FALSE}
# Construct the data
d <- meta(pseq)
d$diversity <- microbiome::diversity(pseq, "shannon")$shannon
# Split the values by group
spl <- split(d$diversity, d$sex)
# Kolmogorov-Smironv test
pv <- ks.test(spl$female, spl$male)$p.value
# Adjust the p-value
padj <- p.adjust(pv)
```

For tutorial on plotting the output of alpha diversity please check [PlotDiversity](PlotDiversity.html)