diversity.Rmd

---
title: "Diversity analyses"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Diversity analyses}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup, message=FALSE, results='hide'}
library(camtrapviz)
library(ggiraph)
library(ggplot2)
```

This vignette shows how to compute diversity indices from camera trap data.

## Import data

```{r}
data(mica, package = "camtraptor")
records <- mica$data$observations
```

## Summarize data

To compute diversity indices, we need the number and proportion of sightings for each species per camera. For that, we use the function `summarize_species` with `by_cam = TRUE`:

```{r}
spp_cam <- summarize_species(records, 
                             spp_col = "vernacularNames.en", 
                             cam_col = "deploymentID",
                             obstype_col = "observationType",
                             count_col = "count",
                             by_cam = TRUE,
                             NA_count_placeholder = 1)

knitr::kable(spp_cam)
```

## Compute diversity indices

Then, we can compute diversity indices by feeding this summary dataframe to the `get_diversity_indices` function.


```{r}
div <- get_diversity_indices(spp_cam,
                             spp_col = "vernacularNames.en",
                             cam_col = "deploymentID")

knitr::kable(div)
```

Let $i = 1 ... S$ denote the species and $j = 1 ... C$ denote the cameras.
$S_j$ is the number of species seen at camera $j$. $N_j$ is the total number of individuals of all species seen at a camera $j$. $n_{ij}$ and $p_{ij}$ represent respectively the count and proportion if individuals of species $i$ seen at a camera $j$. This function computes:

-   richness $R_j = S_j$ (the number of species seen at camera $j$).
-   Shannon index $H_j = -\sum_{i = 1}^{S_j} p_{ij} \ln(p_{ij})$. It ranges between 0 and $+\infty$, zero indicating the lowest diversity.
-   Simpson index $D_j = \sum_{ = 1}^{S_j} \frac{n_{ij}(n_{ij} - 1) }{N_j(N_j - 1)}$.  It ranges between 0 and 1, one indicating the lowest diversity.

Optionally, you can also provide the name of the columns containing counts and proportions (but they default to the name given by the `summarize_species` function). 

```{r}
div <- get_diversity_indices(spp_cam,
                             spp_col = "vernacularNames.en",
                             cam_col = "deploymentID",
                             count_col = "individuals",
                             prop_col = "individuals_prop")
```

## Plot diversity indices

Although it is then simple to use the diversity dataframe to make a custom plot, the helper function `plot_diversity` is provided. 

Here, we plot the richness.

```{r}
plot_diversity(div, 
               div_col = "richness", 
               cam_col = "deploymentID") +
  ggtitle("Species richness")
```

The plot can also be made interactive.

```{r}
pr <- plot_diversity(div, 
                     div_col = "richness", 
                     cam_col = "deploymentID", 
                     interactive = TRUE) +
  ggtitle("Species richness")

girafe(ggobj = pr)
```

In case you want to show more cameras than the ones in the `div` dataframe, you can use the `cam_vec` argument.

```{r}
div_less <- div[1:3, ]
cameras <- unique(div$deploymentID)

# We deleted one camera
unique(div_less$deploymentID)

# But it is still in cameras
cameras
```


```{r}
pr <- plot_diversity(div_less, 
                     div_col = "richness", 
                     cam_col = "deploymentID", 
                     cam_vec = cameras,
                     interactive = TRUE) +
  ggtitle("Species richness")

girafe(ggobj = pr)
```

Finally, by changing the `div_col` argument you can plot multiple diversity indices.

```{r}
ph <- plot_diversity(div, 
                     div_col = "shannon", 
                     cam_col = "deploymentID", 
                     interactive = TRUE) +
  ggtitle("Shannon diversity index")

pd <- plot_diversity(div, 
                     div_col = "simpson", 
                     cam_col = "deploymentID", 
                     interactive = TRUE) +
   ggtitle("Simpson diversity index")

girafe(ggobj = ph) 
girafe(ggobj = pd)
```