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.

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()
)

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.

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

Note

All assemblages should have a number of species strictly higher than the number of functional axes. Computing intersection of convex hulls in space of >5 dimensions is yet impossible with most computers. This function uses R libraries 'betapart' (> =1.5.4) for indices computation. Indices values are stored as dist objects to optimize memory. See below example of how merging distance values in a dataframe with dist.to.df.

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.

Author

Sebastien Villeger and Camille Magneville

Examples

 # 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)
#> [1] "Running w.type=equal on groups=c(Size)"
#> [1] "Running w.type=equal on groups=c(Plant)"
#> [1] "Running w.type=equal on groups=c(Climate)"
#> [1] "Running w.type=equal on groups=c(Seed)"
#> [1] "Running w.type=equal on groups=c(Sugar)"
#> [1] "Running w.type=equal on groups=c(Use,Use,Use)"

# 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)
#> Serial computing of convex hulls shaping assemblages with conv1
#> 
  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |=======                                                               |  10%
  |                                                                            
  |==============                                                        |  20%
  |                                                                            
  |=====================                                                 |  30%
  |                                                                            
  |============================                                          |  40%
  |                                                                            
  |===================================                                   |  50%
  |                                                                            
  |==========================================                            |  60%
  |                                                                            
  |=================================================                     |  70%
  |                                                                            
  |========================================================              |  80%
  |                                                                            
  |===============================================================       |  90%
  |                                                                            
  |======================================================================| 100%
#> Serial computing of intersections between pairs of assemblages with inter_geom_coord
#> 
  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |==                                                                    |   2%
  |                                                                            
  |===                                                                   |   4%
  |                                                                            
  |=====                                                                 |   7%
  |                                                                            
  |======                                                                |   9%
  |                                                                            
  |========                                                              |  11%
  |                                                                            
  |=========                                                             |  13%
  |                                                                            
  |===========                                                           |  16%
  |                                                                            
  |============                                                          |  18%
  |                                                                            
  |==============                                                        |  20%
  |                                                                            
  |================                                                      |  22%
  |                                                                            
  |=================                                                     |  24%
  |                                                                            
  |===================                                                   |  27%
  |                                                                            
  |====================                                                  |  29%
  |                                                                            
  |======================                                                |  31%
  |                                                                            
  |=======================                                               |  33%
  |                                                                            
  |=========================                                             |  36%
  |                                                                            
  |==========================                                            |  38%
  |                                                                            
  |============================                                          |  40%
  |                                                                            
  |==============================                                        |  42%
  |                                                                            
  |===============================                                       |  44%
  |                                                                            
  |=================================                                     |  47%
  |                                                                            
  |==================================                                    |  49%
  |                                                                            
  |====================================                                  |  51%
  |                                                                            
  |=====================================                                 |  53%
  |                                                                            
  |=======================================                               |  56%
  |                                                                            
  |========================================                              |  58%
  |                                                                            
  |==========================================                            |  60%
  |                                                                            
  |============================================                          |  62%
  |                                                                            
  |=============================================                         |  64%
  |                                                                            
  |===============================================                       |  67%
  |                                                                            
  |================================================                      |  69%
  |                                                                            
  |==================================================                    |  71%
  |                                                                            
  |===================================================                   |  73%
  |                                                                            
  |=====================================================                 |  76%
  |                                                                            
  |======================================================                |  78%
  |                                                                            
  |========================================================              |  80%
  |                                                                            
  |==========================================================            |  82%
  |                                                                            
  |===========================================================           |  84%
  |                                                                            
  |=============================================================         |  87%
  |                                                                            
  |==============================================================        |  89%
  |                                                                            
  |================================================================      |  91%
  |                                                                            
  |=================================================================     |  93%
  |                                                                            
  |===================================================================   |  96%
  |                                                                            
  |====================================================================  |  98%
  |                                                                            
  |======================================================================| 100%
#> Serial computing of intersections between pairs of assemblages with inter_rcdd_coord & qhull.opt1
#> 
  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |=======                                                               |  10%
  |                                                                            
  |==============                                                        |  20%
  |                                                                            
  |=====================                                                 |  30%
  |                                                                            
  |============================                                          |  40%
  |                                                                            
  |===================================                                   |  50%
  |                                                                            
  |==========================================                            |  60%
  |                                                                            
  |=================================================                     |  70%
  |                                                                            
  |========================================================              |  80%
  |                                                                            
  |===============================================================       |  90%
  |                                                                            
  |======================================================================| 100%

# merging pairwise beta-diversity indices in a data.frame
dist.to.df(beta_fd_fruits$pairasb_fbd_indices)
#>          x1        x2     jac_diss     jac_turn     jac_nest
#> 1  basket_1  basket_2 8.197396e-16 8.197396e-16 0.000000e+00
#> 2  basket_1  basket_3 8.197396e-16 8.197396e-16 0.000000e+00
#> 3  basket_1  basket_4 9.903938e-01 8.223456e-01 1.680483e-01
#> 4  basket_1  basket_5 9.903938e-01 8.223456e-01 1.680483e-01
#> 5  basket_1  basket_6 9.199830e-01 9.134231e-01 6.559808e-03
#> 6  basket_1  basket_7 9.199830e-01 9.134231e-01 6.559808e-03
#> 7  basket_1  basket_8 9.926040e-01 9.617520e-01 3.085196e-02
#> 8  basket_1  basket_9 9.926040e-01 9.617520e-01 3.085196e-02
#> 9  basket_1 basket_10 9.554245e-01 8.783088e-01 7.711568e-02
#> 10 basket_2  basket_3 8.197396e-16 8.197396e-16 0.000000e+00
#> 11 basket_2  basket_4 9.903938e-01 8.223456e-01 1.680483e-01
#> 12 basket_2  basket_5 9.903938e-01 8.223456e-01 1.680483e-01
#> 13 basket_2  basket_6 9.199830e-01 9.134231e-01 6.559808e-03
#> 14 basket_2  basket_7 9.199830e-01 9.134231e-01 6.559808e-03
#> 15 basket_2  basket_8 9.926040e-01 9.617520e-01 3.085196e-02
#> 16 basket_2  basket_9 9.926040e-01 9.617520e-01 3.085196e-02
#> 17 basket_2 basket_10 9.554245e-01 8.783088e-01 7.711568e-02
#> 18 basket_3  basket_4 9.903938e-01 8.223456e-01 1.680483e-01
#> 19 basket_3  basket_5 9.903938e-01 8.223456e-01 1.680483e-01
#> 20 basket_3  basket_6 9.199830e-01 9.134231e-01 6.559808e-03
#> 21 basket_3  basket_7 9.199830e-01 9.134231e-01 6.559808e-03
#> 22 basket_3  basket_8 9.926040e-01 9.617520e-01 3.085196e-02
#> 23 basket_3  basket_9 9.926040e-01 9.617520e-01 3.085196e-02
#> 24 basket_3 basket_10 9.554245e-01 8.783088e-01 7.711568e-02
#> 25 basket_4  basket_5 0.000000e+00 0.000000e+00 0.000000e+00
#> 26 basket_4  basket_6 9.999978e-01 9.999699e-01 2.794322e-05
#> 27 basket_4  basket_7 9.999978e-01 9.999699e-01 2.794322e-05
#> 28 basket_4  basket_8 1.000000e+00 1.000000e+00 0.000000e+00
#> 29 basket_4  basket_9 1.000000e+00 1.000000e+00 0.000000e+00
#> 30 basket_4 basket_10 9.697201e-01 8.569122e-01 1.128080e-01
#> 31 basket_5  basket_6 9.999978e-01 9.999699e-01 2.794322e-05
#> 32 basket_5  basket_7 9.999978e-01 9.999699e-01 2.794322e-05
#> 33 basket_5  basket_8 1.000000e+00 1.000000e+00 0.000000e+00
#> 34 basket_5  basket_9 1.000000e+00 1.000000e+00 0.000000e+00
#> 35 basket_5 basket_10 9.697201e-01 8.569122e-01 1.128080e-01
#> 36 basket_6  basket_7 7.075763e-16 7.075763e-16 0.000000e+00
#> 37 basket_6  basket_8 1.000000e+00 1.000000e+00 0.000000e+00
#> 38 basket_6  basket_9 1.000000e+00 1.000000e+00 0.000000e+00
#> 39 basket_6 basket_10 1.000000e+00 1.000000e+00 0.000000e+00
#> 40 basket_7  basket_8 1.000000e+00 1.000000e+00 0.000000e+00
#> 41 basket_7  basket_9 1.000000e+00 1.000000e+00 0.000000e+00
#> 42 basket_7 basket_10 1.000000e+00 1.000000e+00 0.000000e+00
#> 43 basket_8  basket_9 2.777536e-15 2.777536e-15 0.000000e+00
#> 44 basket_8 basket_10 9.783752e-01 9.648085e-01 1.356666e-02
#> 45 basket_9 basket_10 9.783752e-01 9.648085e-01 1.356666e-02