funct.dist {mFD}

Compute functional distance between species

Description

For a given combination of traits, this function returns the functional distance matrix between species.

Usage

funct.dist(
  sp_tr,
  tr_cat,
  metric,
  scale_euclid = "scale_center",
  ordinal_var = "classic",
  weight_type = "equal",
  stop_if_NA = TRUE
)

Arguments

sp_tr

a data frame of traits values (columns) for each species (rows).

tr_cat

a data frame containing three columns for each trait (rows):

• trait_name: the name of all traits as in sp_tr data frame;

• trait_type: the category code for each trait as followed: N for Nominal traits (factor variable), O for Ordinal traits (ordered variable), C for Circular traits (integer values), Q for quantitative traits (numeric values) that is allowed only if there are at least 2 species with the same value, and F for fuzzy traits (i.e. described with several values defined with several column);

• fuzzy_name: name of fuzzy-coded trait to which 'sub-trait' belongs (if trait is not fuzzy, ignored so could be trait name or NA).

• trait_weight: Optional, a numeric vector of length n (traits number) to specify a weight for each trait.

metric

the distance to be computed: euclidean, the Euclidean distance, gower, the Classical Gower distance as defined by Gower (1971), extent by de Bello et al. (2021) and based on the gawdis function.

scale_euclid

only when computing euclidean distance a string value to compute (or not) scaling of quantitative traits using the tr.cont.scale function. Possible options are: range (standardize by the range: ({x' = x - min(x) )} / (max(x) - min (x))) center (use the center transformation: x' = x - mean(x)), scale (use the scale transformation: x' = \frac{x}{sd(x)}), scale_center (use the scale-center transformation: x' = \frac{x - mean(x)}{sd(x)}), or noscale traits are not scaled Default is scale_center.

ordinal_var

a character string specifying the method to be used for ordinal variables (i.e. ordered). classic simply treats ordinal variables as continuous variables; metric refers to Eq. 3 of Podani (1999); podani refers to Eqs. 2a-b of Podani (1999), Both options convert ordinal variables to ranks. Default is classic.

weight_type

the type of used method to weight traits. user user defined weights in tr_cat, equal all traits having the same weight. More methods are available using gawdis from gawdis package. To compute gower distance with fuzzy trait and weight please refer to gawdis. Default is equal.

stop_if_NA

a logical value to stop or not the process if the sp_tr data frame contains NA. Functional measures are sensitive to missing traits. For further explanations, see the Note section. Default is TRUE.

Value

a dist object containing distance between each pair of species.

Note

If the sp_tr data frame contains NA you can either chose to compute anyway functional distances (but keep in mind that Functional measures are sensitive to missing traits!) or you can delete species with missing or extrapolate missing traits (see Johnson et al. (2020)).

Author(s)

Nicolas Loiseau and Sebastien Villeger

References

de Bello et al. (2021) Towards a more balanced combination of multiple traits when computing functional differences between species. Method in Ecology and Evolution, 12, 443-448.
Gower (1971 ) A general coefficient of similarity and some of its properties. Biometrics, 27, 857-871.
Johnson et al. (2020) Handling missing values in trait data. Global Ecology and Biogeography, 30, 51-62.
Podani (1999) Extending Gower's general coefficient of similarity to ordinal characters, Taxon, 48, 331-340.

Examples

# Load Species x Traits data
data("fruits_traits", package = "mFD")

# Load Traits x Categories data
data("fruits_traits_cat", package = "mFD")

# Remove fuzzy traits for this example and thus remove lat column:
fruits_traits     <- fruits_traits[ , -c(6:8)]
fruits_traits_cat <- fruits_traits_cat[-c(6:8), ]
fruits_traits_cat <- fruits_traits_cat[ , -3]

# Compute Functional Distance
sp_dist_fruits <- mFD::funct.dist(sp_tr         = fruits_traits,
                                  tr_cat        = fruits_traits_cat,
                                  metric        = "gower",
                                  scale_euclid  = "scale_center",
                                  ordinal_var   = "classic",
                                  weight_type   = "equal",
                                  stop_if_NA    = TRUE)
sp_dist_fruits