---
title: "Computing functional diversity indices and community weighted means for fishes."
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Computing functional diversity indices and community weighted means for fishes.}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = identical(Sys.getenv("NOT_CRAN"), "true")
)
```

The **fwtraits** access the www.freshwaterecology.info database that contains several ecological parameters, traits, and indicators used in biogeographical modeling, functional diversity and taxonomic assessments, and environmental monitoring. These are grouped based on the taxonomic groups, including macroinvertebrates, fishes, phytoplankton, phytobenthos, and macrophytes. Therefore, in this workflow, we demonstrated using ecological parameters from the database in assessing functional diversity. 


```{r setup, warning=FALSE}
library(fwtraits)
library(ggplot2)
```

### Fishes data used in the analysis

We tested using the species data with both spatial coordinates to auto-generate sites or sites already indicated in the sites or species data.

```{r data}
data("speciesdata")

set.seed(1135)
speciesdata$abund <- rnorm(n = nrow(speciesdata), 4.3, 1.2)

#species with geographical coordinates

geospdata <- speciesdata |> 
  sf::st_as_sf(coords = c('decimalLongitude', 'decimalLatitude'), 
               crs = sf::st_crs(4326))

```

### Retrieving the ecological parameters from the database

We considered two ecological references for fishes: rheophily habitat, spawning habitat, and feeding diet adult. These were selected because most species have records, reducing missing values that might have required imputation. 

It should be noted that imputing for missing traits is outside the scope of this package. So, species that do not have records were dropped when computing the functional diversity indices or community weighted means.

```{r retrievedata}

fishtraits <- fw_fetchdata(data = speciesdata, 
                         ecoparams = c('rheophily habitat', 'spawning habitat',
                                       'feeding diet adult'), 
                         taxonomic_column = 'scientificName',
                         organismgroup = 'fi')
```

#### 1. Compute functional diversity indices 

These are computed by setting **`FD to TRUE`** and **abund** parameter must be provided. They the indices are computed using the **`FD`** package (Laliberté & Legendre 2010). The indices tested included Functional richness (FRic), species richness (SRic), Functional evenness (FEve), Functional diversity (FDiv), Functional dispersion (FDis), and Rao quotient (Rao Q).


```{r commputefdindies}

#fd indices calculated when abundance  is provided.

fdindices <- fw_fdcompute(fwdata = fishtraits, 
                        sitesdata = speciesdata,
                        sites = 'waterBody',
                        species = 'scientificName',
                        abund = 'abund',
                        FD = TRUE)
head(fdindices, 3)

#functional richness only: when abundance is not provided.
fdric<- fw_fdcompute(fwdata = fishtraits, 
                        sitesdata = speciesdata,
                        sites = 'waterBody',
                        species = 'scientificName',
                        FD = TRUE)
head(fdric, 3)
```

#### 2. Compute Functional Diversity indices using autogenerated sites.

```{r commputefdspatial}

#fd indices calculated when abundance  is provided.

geofdind <- fw_fdcompute(fwdata = fishtraits, 
                        sitesdata = geospdata,
                        species = 'scientificName',
                        abund = 'abund',
                        FD = TRUE)
head(geofdind, 3)

#functional richness only: when abundance is not provided.
geofd <- fw_fdcompute(fwdata = fishtraits, 
                        sitesdata = geospdata,
                        species = 'scientificName',
                        FD = TRUE)
head(geofd, 3)
```

#### 3. Visualisation of the ecological paramter for each index.

```{r viz, fig.width = 7, fig.height= 4, fig.align='center', warning=FALSE}

df <- fdindices |> tidyr::gather('fdind', "vals", -site)
                                 
ggplot(data = df, aes(site, vals, fill = fdind))+
  geom_bar(stat = 'identity')+
  scale_fill_viridis_d()+
  theme(legend.position = "none",
        axis.text.x = element_text(angle = 45, hjust = 1, size = 7))+
  facet_wrap(~fdind, scales ='free_y')+
  scale_y_continuous(expand = expansion(mult = c(0, 0.1)))+
  labs(x='sites', y='FD indices')

#Functional richness

dffric <- fdric |> tidyr::gather('fdind', "vals", -site)
                                 
ggplot(data = dffric, aes(site, vals, fill = fdind))+
  geom_bar(stat = 'identity')+
  scale_fill_viridis_d()+
  theme(legend.position = "none",
        axis.text.x = element_text(angle = 45, hjust = 1, size = 7))+
  facet_wrap(~fdind, scales ='free_y')+
  scale_y_continuous(expand = expansion(mult = c(0, 0.1)))+
  labs(x='Sites', y='FD indices')
  
```



#### 4. Compute community weighted means.

Community weighted means measures how traits vary with environmental change (Guy-Haim & Bouchet 2025).

```{r cmwmeans}
cwmdata <- fw_fdcompute(fwdata = fishtraits, 
                        sitesdata = speciesdata,
                        sites = 'waterBody',
                        species = 'scientificName',
                        abund = 'abund',
                        FD = FALSE)
head(cwmdata, 3)
```

#### 5. Compute community weighted means using raw traits.

In this approach, this does not require fuzzy coding of the trait data. This is necessary for community weighted means. 
 
```{r cwmeansnodummy}
cwmdata2 <- fw_fdcompute(fwdata = fishtraits, 
                        sitesdata = speciesdata,
                        sites = 'waterBody',
                        species = 'scientificName',
                        abund = 'abund',
                        FD = FALSE, dummy = FALSE)
head(cwmdata2, 3)
```

### Refereences 

1. Laliberté, E., & Legendre, P. (2010). A distance‐based framework for measuring functional diversity from multiple traits. Ecology, 91(1), 299-305.

2. Guy-Haim, T., & Bouchet, V. M. (2025). Beyond taxonomy: A framework for biological trait analysis to assess the functional structure of benthic foraminiferal communities. Marine Pollution Bulletin, 213, 117699.
