---
title: "Continuous Traits Framework"
author: "Camille Magneville"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Continuous Traits Framework}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}

---



# About this tutorial

<br />

This tutorial explains the workflow used to compute functional space based on
continuous traits and it shows how to retrieve species coordinates and species
functional distances in the functional space.

<br />

**DATA** This tutorial uses a dataset from one of the 80 CESTES database 
Jeliazkov & the CESTES consortium (2019)) based on [Villeger _et al._
2012]
(https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0040679).
This data frame contains 45 fish species from the Terminos Lagoon (Gulf of
Mexico) gathered into 36 sites considered as assemblages. Each species is
described with 16 continuous morphological traits.

<br />

When the dataset **only** gathers continuous traits, the functional space can
be computed using one trait for one dimension or using Principal Component
Analysis (PCA: convert correlations among samples into a 2D plot). **NB** Using 
a PCoA on continuous traits and euclidean distance is the same than using a PCA
(clusters made by minimizing the linear distance (PCoA) are the same as those
obtained by maximizing linear correlations (PCA)).


<br />


# 1. Load dataset

<br />


The species traits data frame has rows corresponding to species and columns
corresponding to traits. The different traits are summed up in the following
table:

<br />

| Trait name | Trait signification              | 
|:----------:|:--------------------------------:|
| logM       | log(mass)                        |
| Ogsf       | Oral gape surface                |
| OgSh       | Oral gape shape                  |
| OgPo       | Oral gape position               |
| GrLg       | Gill raker length                |
| GtLg       | Gut length                       |
| EySz       | Eye size                         |
| EyPo       | Eye position                     |
| BdSh       | Body transversal shape           |
| BdSf       | Body transversal surface         |
| PfPo       | Pectoral fin position            |
| PfSh       | Aspect ratio of the pectoral fin |
| CpHt       | Caudal peduncle throttling       |
| CfSh       | Aspect ratio of the caudal fin   |
| FsRt       | Fins surface ratio               |
| FsSf       | Fins surface to body size ratio  |
 
 <br />
 
To work with `mFD` with only continuous traits, you must load two objects:

<br />

* `sp_tr`:  species x traits data frame


```{r, warning=FALSE}
# load dataset:
sp_tr <- read.csv(system.file("extdata", "data_cestes_sp_tr.csv", 
                              package = "mFD"), dec = ",", sep = ":")

rownames(sp_tr) <- sp_tr$"Sp"
sp_tr <- sp_tr[ , -1]

# display the table:
knitr::kable(head(sp_tr), 
             caption = "Species x Traits data frame based on *CESTES* dataset")
```

<br />

* `asb_sp_w`: species x assemblages data frame summarizing biomass recorded in a volume of 4500m<sup>3</sup> 
per site and per species:


```{r, warning = FALSE}
# load dataset:
asb_sp_w <- read.csv(system.file("extdata", "data_cestes_asb_sp_w.csv", 
                                 package = "mFD"), dec = ",", sep = ":")

rownames(asb_sp_w) <- paste0("site", sep = "_", asb_sp_w$Sites)
asb_sp_w <- asb_sp_w[ , -1]

asb_sp_w$Urobatis_jamaicensis <- as.numeric(asb_sp_w$Urobatis_jamaicensis)

# remove sites 12, 23, 35 because FRic can not be computed on it...
# ... (for a clean example):
asb_sp_w <- asb_sp_w[-c(11, 22, 33), ]

# display the table:
knitr::kable(asb_sp_w[1:7, 1:6], 
             caption = "Species x Assemblages data frame based on *CESTES* dataset for the first six species and first seven sites")
```

<br />


# 2. Compute the functional space

<br />


Based on the species-trait data frame or the species-standardized traits
data frame, `mFD` allows to build a functional space based on a PCA or using each
trait as a dimension. (**NB** Using up to the 1.0.3 version of the `mFD` package 
does not allow weighting continuous traits, it will be done in a next version of the 
package.  You can use the [`col.w`](https://rdrr.io/cran/FactoMineR/man/PCA.html) 
argument of the PCA function of the FactomineR package.). The function used to 
compute functional space with continuous traits is called `mFD::tr.cont.fspace()`
and is used as follow:

<br />

**USAGE**

```{r, results = "hide"}
mFD::tr.cont.fspace(
  sp_tr        = sp_tr, 
  pca          = TRUE, 
  nb_dim       = 7, 
  scaling      = "scale_center",
  compute_corr = "pearson")
```

<br />

It takes as inputs: 

* the *sp_tr* data frame 

* a *pca* argument that must be set to TRUE if you want to compute a PCA or to
FALSE if you want to use each trait as a dimension to construct the
multidimensional space

* a *nb_dim* argument referring to the maximum number of dimensions for
multidimensional functional spaces. Final number of dimensions depends on the
number of positive eigenvalues obtained with PCA if *pca = TRUE*
or the number of traits used if *pca = FALSE*. **NB** High value for
*nb_dim* can increase computation time.

* a *scaling* argument allowing traits values to be standardized. They can be
standardized in several ways: standardization by the range value of the trait,
center-transformation, scale transformation or scale-center transformation can
be used. You can also chose not to standardize traits values.
**NOTE**  Scaling ensures that trait-based distances and distances in the functional
space have the same maximum. Scaling distances implies that the quality of the
functional space accounts for congruence in distances rather than their equality

* a *compute_corr* argument which refers to a string value to compute Pearson
correlation coefficients between traits using *"pearson"* or not using *"none"*.
  
<br />

In this example, we will compute a PCA based on a maximum number of 7 dimensions
and get Pearson's correlation coefficients:

 <br />

```{r, results = "hide"}
fspace <- mFD::tr.cont.fspace(
  sp_tr        = sp_tr, 
  pca          = TRUE, 
  nb_dim       = 10, 
  scaling      = "scale_center",
  compute_corr = "pearson")
```

<br />

If the PCA is computed, the output contains:

* quality metrics for spaces from 2 dimensions to *nb_dim* dimensions:

**NB** **mean absolute deviation (mad)** reflects the actual magnitude of errors
that affect distances, hence FD metrics ;  **mean squared deviation (msd)**
reflects the potential risk associated with a few species pairs being strongly
misplaced in the functional space ([Maire _et al._
(2015)](https://onlinelibrary.wiley.com/doi/full/10.1111/geb.12299)).

<br />

```{r}
fspace$"quality_metrics"
```  

<br />

**NB** The lower the quality metric is, the better the quality of your space is.
Here, thanks to mAD and mSD value, we can see that as the number of dimensions
increases, the quality increases. However, to decrease computation time, we can
chose to work with the 6D space which has good quality of functional space.
Generally, you must keep in mind a trade-off between the number of axes and
quality of functional space. Increasing the number of functional axes increases
computation time.

<br />

* eigenvalues, percentage of variance explained and cumulative percentage of variance explained for each axis up to *nb_dim* dimensions:

<br />

```{r}
fspace$"eigenvalues_percentage_var"
```  

<br />

* a matrix of species coordinates in the functional space:

<br />

```{r}
head(fspace$"sp_faxes_coord")
```

<br />

* a dist object containing species euclidean distances in the functional space
(here 5D space and for the first five species):
  
<br />

```{r}
dist_mat <- as.matrix(fspace$sp_dist_multidim$"6D")
dist_mat[1:5, 1:5]
```

<br />

* a dist object containing species distances based on traits
(here for the first five species):
  
<br />

```{r}
dist_mat <- as.matrix(fspace$sp_dist_init)
dist_mat[1:5, 1:5]
```
<br />

* a correlation matrix containing correlation between traits and their
associated pvalue:
  
<br />

```{r}
fspace$"tr_correl"
```

<br />

Here we can notice that there is no strong correlation between traits. 
**NB** However, if some strong correlation is to be found, then one of the two
correlated trait can be remove from the analysis.

If the PCA is not computed, outputs are the same except that mad and msd are not
computed and that only one distance object is returned.

<br />


# 3. Plot functional space, compute and illustrate indices

<br />

Then, based on the species coordinates matrix, steps are similar as those listed
in the
[mFD General Workflow](https://cmlmagneville.github.io/mFD/articles/mFD_general_workflow.html), 
from step 5 till the end.

<br />

# References

<br />

- Maire _et al._ (2015) 
How many dimensions are needed to accurately assess functional diversity? 
A pragmatic approach for assessing the quality of functional spaces.
_Global Ecology and Biogeography_, **24**, 728-740.

- Villeger _et al._ (2012) 
Low Functional beta Diversity Despite High Taxonomic beta Diversity among 
Tropical Estuarine Fish Communities.
_PLoS ONE_, **7**, e40679.