PRE_FATE.speciesDistance: Computation of distances between species based on traits and...
In MayaGueguen/RFate: Vegetation modelling with the FATE model

Description Usage Arguments Details Value Author(s) See Also Examples

View source: R/PRE_FATE.speciesDistance.R

This script is designed to create a distance matrix between species, combining functional distances (based on functional trait values) and niche overlap (based on co-occurrence of species).

PRE_FATE.speciesDistance(
  mat.traits,
  mat.overlap,
  opt.maxPercent.NA = 0,
  opt.maxPercent.similarSpecies = 0.25,
  opt.min.sd = 0.3
)

`mat.traits`	a `data.frame` with at least 3 columns : `species` the ID of each studied species `GROUP` a factor variable containing grouping information to divide the species into data subsets (see `Details`) `...` one column for each functional trait
`mat.overlap`	two options : a `data.frame` with 2 columns : `species` the ID of each studied species `raster` path to raster file with species distribution a dissimilarity structure representing the niche overlap between each pair of species. It can be a `dist` object, a `niolap` object, or simply a `matrix`.
`opt.maxPercent.NA`	(optional) default `0`. Maximum percentage of missing values (`NA`) allowed for each trait (between `0` and `1`)
`opt.maxPercent.similarSpecies`	(optional) default `0.25`. Maximum percentage of similar species (same value) allowed for each trait (between `0` and `1`)
`opt.min.sd`	(optional) default `0.5`. Minimum standard deviation allowed for each trait (trait unit)

This function allows to obtain a distance matrix between species, based on two types of distance information :

Functional traits :
- The GROUP column is required if species must be separated to have one final distance matrix per GROUP value.
  If the column is missing, all species will be considered as part of a unique dataset.
- The traits can be qualitative or quantitative, but previously identified as such
  (i.e. with the use of functions such as as.numeric, as.factor and ordered).
- Functional distance matrix is calculated with Gower dissimilarity, using the gowdis function.
- This function allows NA values.
  However, too many missing values lead to misleading results. Hence, 3 parameters allow the user to play with the place given to missing values, and therefore the selection of traits that will be used for the distance computation :
  
  opt.maxPercent.NA
  traits with too many missing values are removed
  
  opt.maxPercent
  .similarSpecies
  traits with too many similar values are removed
  
  opt.min.sd
  traits with too little variability are removed
Niche overlap :
- If a data.frame is given, the degree of niche overlap will be computed using the niche.overlap.

Functional distances and niche overlap informations are then combined according to the following formula :

\text{mat.DIST}_{sub-group} = \frac{[ \text{mat.OVERLAP}_{sub-group} + \text{mat.FUNCTIONAL}_{sub-group} * n_{traits} ]}{[ n_{traits} + 1 ]}

meaning that distance matrix obtained from functional information is weighted by the number of traits used.

A dist object corresponding to the distance between each pair of species, or a list of dist objects, one for each GROUP value.

The information is written in ‘PRE_FATE_DOMINANT_speciesDistance.csv’ file (or if necessary, one file is created for each group).

Maya Guéguen

gowdis, niche.overlap

## Load example data
data(DATASET_Bauges_PFG)

## Species traits
tab.traits = DATASET_Bauges_PFG$dom.traits
str(tab.traits)

## Species niche overlap (similarity distance)
tab.overlap = DATASET_Bauges_PFG$dom.dist_overlap
tab.overlap[1:5, 1:5]

## Give warnings -----------------------------------------------------------------------------
sp.DIST = PRE_FATE.speciesDistance(mat.traits = tab.traits
                                   , mat.overlap = as.matrix(tab.overlap))
str(sp.DIST)

## Not run: 
require(foreach)
require(ggplot2)
require(ggdendro)
pp = foreach(x = names(sp.DIST)) %do%
{
  hc = hclust(sp.DIST[[x]])
  pp = ggdendrogram(hc, rotate = TRUE) +
    labs(title = paste0("Hierarchical clustering based on species distance "
                        , ifelse(length(names(sp.DIST)) > 1
                        , paste0("(group ", x, ")")
                        , "")))
  return(pp)
}
plot(pp[[1]])
plot(pp[[2]])
plot(pp[[3]])

## End(Not run)

## Change parameters to allow more NAs (and change traits used) ------------------------------
sp.DIST = PRE_FATE.speciesDistance(mat.traits = tab.traits
                                   , mat.overlap = as.matrix(tab.overlap)
                                   , opt.maxPercent.NA = 0.05
                                   , opt.maxPercent.similarSpecies = 0.3
                                   , opt.min.sd = 0.3)
str(sp.DIST)