---
title: "Functional diversity with trait probability densities"
author: "Barnabas H. Daru"
date: "`r format(Sys.time(), '%B %d, %Y')`"
output: rmarkdown::html_vignette
bibliography: phyloregion.bib
vignette: >
   %\VignetteIndexEntry{Functional diversity with trait probability densities}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 7,
                      fig.height = 4, message = FALSE, warning = FALSE)
```

## Introduction

Species richness counts how many species live in a place. Functional
diversity asks what those species are like: how tall they grow, whether they
are trees or herbs, how big their seeds are. Two places can have the same
number of species but very different traits, and a place can keep its number
of species while its traits change.

`phyloregion` measures functional diversity with trait probability densities
[TPD, @Carmona2016]. Each species is a small hill of probability placed at its
traits in trait space. A grid cell's trait spectrum is the sum of its species'
hills. From these spectra we get functional alpha diversity for each grid cell,
functional beta diversity between grid cells, functional regions, and, for a
whole group of species, the trait spectrum of threatened versus non-threatened
species and its erosion under extinction scenarios [@Carmona2021].

The functions work with any mix of continuous and categorical traits and use
the same sparse-matrix approach as `phylobeta`, so they are fast for large
community matrices.

## 1. Data

We use the `africa` data: a grid-cell × species matrix for woody plants of
southern Africa, with traits for each species. We use one continuous trait,
maximum height (log-transformed, because heights are skewed), and one
categorical trait, growth habit.

```{r}
library(phyloregion)
library(terra)

data(africa)
p <- vect(system.file("ex/sa.json", package = "phyloregion"))

tr <- data.frame(species = africa$trait$species,
                 height = log10(africa$trait$h_max),
                 habit = africa$trait$habit)
head(tr)
```

The first column must contain the species names. Every other column is used as
a trait: numeric columns are treated as continuous and character or factor
columns as categorical. Species with missing values are left out.

## 2. How the trait space is built

* Continuous traits are standardized and become the axes of trait space
  (a ruler for one trait, a sheet for two, a box for three).
* Each combination of categories gets its own trait space, so a tree's density
  never spills into the trait space of herbs.
* With more than three continuous traits or more than eight combinations of
  categories, all traits are summarized by two mixed principal component axes.
* Each species' hill is a normal kernel with a width chosen by `bw.nrd0`, cut so
  that it keeps 99% of its density (`quantile = 0.99`).

## 3. Functional alpha diversity

```{r}
fa <- tpd_alpha(africa$comm, tr)
head(fa)
```

`tpd_alpha` returns one row per grid cell:

* `SR`: species richness
* `FRic`: functional richness, the volume of trait space occupied
* `FEve`: functional evenness, how evenly the density is spread
* `FRed`: functional redundancy, the average number of extra species sharing
  the same traits
* `CWM_height`: community-weighted mean of each continuous trait
* `share_`: share of each category

Map them with the grid-cell polygons:

```{r, fig.height = 3.2}
m <- merge(p, fa, by = "grids")
par(mfrow = c(1, 3), mar = c(1, 1, 2, 3))
plot(m, "FRic", main = "FRic", axes = FALSE, border = NA,
     col = hcl.colors(20, "YlOrRd", rev = TRUE))
plot(m, "FEve", main = "FEve", axes = FALSE, border = NA,
     col = hcl.colors(20, "YlOrRd", rev = TRUE))
plot(m, "FRed", main = "FRed", axes = FALSE, border = NA,
     col = hcl.colors(20, "YlOrRd", rev = TRUE))
```

## 4. Functional beta diversity

`tpd_beta` compares the trait spectra of every pair of grid cells. The total
dissimilarity is one minus their overlap. It is split into two parts
[@Carmona2016]:

* `beta.unique`: density in trait space used by only one of the two grid cells
  (like turnover)
* `beta.nested`: different amounts of density in trait space used by both
  (like nestedness)

```{r}
fb <- tpd_beta(africa$comm, tr)
sapply(fb, function(d) round(mean(d), 3))
```

`tpd_beta_core` returns the shared and unshared parts of each pair, in the same
way as `phylobeta_core`.

## 5. Functional regions

Functional beta diversity can be used like any other beta diversity in
`phyloregion`. Grid cells with very few species look completely different from
everything else, so we keep grid cells with at least 10 species before
clustering.

```{r, fig.height = 4.5}
keep <- fa$grids[fa$SR >= 10]
fbk <- as.dist(as.matrix(fb$beta.total)[keep, keep])
fr <- phyloregion(fbk, k = 5, pol = p)
plot(fr)
```

## 6. Trait spectra of groups: threatened versus non-threatened

Instead of grid cells, we can compare groups of species, as
@Carmona2021 did for the global spectra of plants and vertebrates.
`tpd_groups` turns a vector of group labels into a groups × species matrix
that can be used in `tpd_alpha` and `tpd_beta`.

```{r}
status <- ifelse(africa$IUCN$IUCN %in% c("CR", "EN", "VU"),
                 "threatened", "not_threatened")
names(status) <- africa$IUCN$Species
g <- tpd_groups(status)
rowSums(g)

tpd_alpha(g, tr)[, c("grids", "SR", "FRic", "FRed", "CWM_height")]
round(as.matrix(tpd_beta(g, tr)$beta.total), 3)
```

In this example, threatened species are on average shorter (a smaller
`CWM_height`) and occupy a part of the trait space that differs from the
spectrum of non-threatened species.

## 7. Extinction scenarios

`tpd_extinction` removes species at random according to their extinction
probabilities, many times, and compares the trait spectrum before and after.
As a null model, the same number of species is removed completely at random.
The probabilities below are hypothetical values for each IUCN category; use
probabilities suited to your question.

```{r}
pr <- c(LC = 0.001, NT = 0.01, VU = 0.1, EN = 0.5, CR = 0.9)
prob <- setNames(pr[africa$IUCN$IUCN], africa$IUCN$Species)
set.seed(1)
ex <- tpd_extinction(tr, prob, nsim = 50)
ex$summary[ex$summary$quantity %in% c("lost", "FRic", "overlap"), ]
```

If the overlap with the current spectrum is lower for extinctions than for
random losses of the same number of species, extinctions are reorganizing the
trait spectrum more than expected by chance.

## Session info

```{r}
sessionInfo()
```

## References
