Computation of traits distances between species

Source: R/PRE_FATE.speciesDistanceTraits.R

This script is designed to create a distance matrix between species, based on functional trait values.

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

Arguments

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

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)

Value

A matrix containing functional distances between each pair of species, calculated as 1 - Schoeners D.

Details

This function allows to obtain a distance matrix between species (1 - Schoeners D), based on functional traits information :

  • 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

See also

gowdis

Author

Maya Guéguen

Examples


## Load example data
Champsaur_PFG = .loadData('Champsaur_PFG', 'RData')

## Species traits
tab.traits = Champsaur_PFG$sp.traits
tab.traits = tab.traits[, c('species', 'GROUP', 'MATURITY', 'LONGEVITY'
                            , 'HEIGHT', 'DISPERSAL', 'LIGHT', 'NITROGEN')]
str(tab.traits)

## Give warnings -------------------------------------------------------------
DIST.traits = PRE_FATE.speciesDistanceTraits(mat.traits = tab.traits)
str(DIST.traits)

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

if (FALSE) {
require(foreach); require(ggplot2); require(ggdendro)
pp = foreach(x = names(DIST.traits)) %do%
  {
    hc = hclust(as.dist(DIST.traits[[x]]))
    pp = ggdendrogram(hc, rotate = TRUE) +
      labs(title = paste0('Hierarchical clustering based on species distance '
                          , ifelse(length(names(DIST.traits)) > 1
                                   , paste0('(group ', x, ')')
                                   , '')))
    return(pp)
  }
plot(pp[[1]])
plot(pp[[2]])
plot(pp[[3]])
}