mFD (version 1.0.7)

beta.fd.multidim: Compute Functional beta-Diversity indices for pairs of assemblages in a multidimensional space

Description

Computes a set of indices of pairwise functional beta-diversity (dissimilarity and its turnover and nestedness-resultant components) based on overlap between convex hulls in a multidimensional space. For details about indices formulas see Villeger et al. (2013). This functions stands on functional.betapart.core.pairwise.

Usage

beta.fd.multidim(
  sp_faxes_coord,
  asb_sp_occ,
  check_input = TRUE,
  beta_family = "Jaccard",
  details_returned = TRUE,
  betapart_step = TRUE,
  betapart_chullopt = list(conv1 = "Qt", conv2 = "QJ"),
  betapart_para = FALSE,
  betapart_para_opt = betapart::beta.para.control()
)

Value

A list with:

• pairasb_fbd_indices a list with for each index a dist object with values for all pairs of assemblages. Indices names start with the abbreviation of the type of dissimilarity index ('jac' for Jaccard-like and 'sor' for Sorensen-like dissimilarity) and end with abbreviation of component ('diss': dissimilarity, 'turn' its turnover component, and 'nest' its nestedness-resultant component).

• if store_details is TRUE,

• details_beta list: inputs a list with sp_faxes_coord and asb_sp_occ on which indices were computed (required for drawing graphics), pool_vertices a list of vectors (1 per assemblage) with names of species being vertices of the convex hull shaping all species; asb_FRic a vector with volume of the convex hull shaping each assemblage (relative to volume filled by all species) ; asb_vertices a list of vectors (1 per assemblage) with names of species being vertices of the convex hull

Arguments

sp_faxes_coord

a matrix with coordinates of species (rows) on functional axes (columns). Species coordinates have been retrieved thanks to tr.cont.fspace or quality.fspaces.

asb_sp_occ

a matrix with presence/absence (coded as 0/1) of species (columns) in a set of assemblages (rows).

check_input

a logical value defining whether inputs are checked before computation of indices. Possible error messages will thus may be more understandable for the user than R error messages. Default: check_input = TRUE.

beta_family

a character string for the type of beta-diversity index to use, 'Jaccard' (default) and/or 'Sorensen'.

details_returned

a logical value indicating whether the user wants to details_returned. Details are used in the graphical function beta.multidim.plot and thus must be kept if the user want to have graphical outputs for the computed indices.

betapart_step

a logical value indicating whether the computation progress should be displayed in the R console. Default: betapart_step = TRUE.

betapart_chullopt

a A list of two named vectors of character conv1 and conv2 defining the options that will be used to compute the convex hulls (through the options of geometry::convhulln function). For further details see help of functional.betapart.core.pairwise. Default: betapart_chullopt = c(conv1 = 'Qt', conv2 = 'QJ').

betapart_para

a logical value indicating whether internal parallelization should be used to compute pairwise dissimilarities. Default: betapart_para = FALSE.

betapart_para_opt

a list with details about parallelization. Default value means those parameters are set according to computer specifications. nc is the number of cores (default = 4), type is a character string with code of method used (default PSOCK), LB is a boolean specifying whether load-balancing is applied (default is TRUE) and size is a numeric value for number of tasks performed at each time (default is 1). See help of functional.betapart.core.pairwise for more details.

Author

Sebastien Villeger and Camille Magneville

References

Villeger et al. (2013) Decomposing functional beta-diversity reveals that low functional beta-diversity is driven by low functional turnover in European fish assemblages. Global Ecology and Biogeography, 22, 671-681.

Examples

if (FALSE) {
 # Load Species*Traits dataframe:
data('fruits_traits', package = 'mFD')

# Load Assemblages*Species dataframe:      
data('baskets_fruits_weights', package = 'mFD') 

# Load Traits categories dataframe:
data('fruits_traits_cat', package = 'mFD') 
 
# 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)

# Compute functional spaces quality to retrieve species coordinates matrix:
fspaces_quality_fruits <- mFD::quality.fspaces(
 sp_dist             = sp_dist_fruits, 
 maxdim_pcoa         = 10,
 deviation_weighting = 'absolute',
 fdist_scaling       = FALSE,
 fdendro             = 'average')
 
# Retrieve species coordinates matrix:
sp_faxes_coord_fruits <- fspaces_quality_fruits$details_fspaces$sp_pc_coord

# Get the occurrence dataframe:
asb_sp_fruits_summ <- mFD::asb.sp.summary(asb_sp_w = baskets_fruits_weights) 
asb_sp_fruits_occ <- asb_sp_fruits_summ$'asb_sp_occ'

# Compute beta diversity indices:
beta_fd_fruits <- mFD::beta.fd.multidim(
  sp_faxes_coord   = sp_faxes_coord_fruits[, c('PC1', 'PC2', 'PC3', 'PC4')], 
  asb_sp_occ       = asb_sp_fruits_occ,
  check_input      = TRUE,
  beta_family      = c('Jaccard'),
  details_returned = TRUE)

# merging pairwise beta-diversity indices in a data.frame
dist.to.df(beta_fd_fruits$pairasb_fbd_indices)
}