Package 'mFD'

Compute the set of indices based on number of species in Functional Entities

Description

This function computes the set of indices based on number of species in Functional Entities (FEs) following Mouillot et al. (2014).

Usage

alpha.fd.fe(
  asb_sp_occ,
  sp_to_fe,
  ind_nm = c("fred", "fored", "fvuln"),
  check_input = TRUE,
  details_returned = TRUE
)

Arguments

asb_sp_occ	a matrix linking occurrences (coded as 0/1) of species (columns) in a set of assemblages (rows). Warning: An assemblage must contain at least one species.
sp_to_fe	a list with details of species clustering into FE from sp.to.fe.
ind_nm	a vector of character strings with the names of functional diversity indices to compute among 'fred', 'fored' and 'fvuln'. Indices names must be written in lower case letters. Default: all the indices are computed.
check_input	a logical value indicating whether key features the inputs are checked (e.g. class and/or mode of objects, names of rows and/or columns, missing values). If an error is detected, a detailed message is returned. Default: check.input = TRUE.
details_returned	a logical value indicating whether details about indices computation should be returned. These details are required by alpha.fd.fe.plot to plot FEs indices.

Value

A list with:

• asb_fdfe a matrix containing for each assemblage (rows), values of functional diversity indices (same names than in 'ind_nm') as well as the number of species ('nb_sp') and the number of FE (nb_fe);

• if details_returned is TRUE,

• details_fdfe a list with asb_fe_nbsp a matrix with number of species per FE in each assemblage.

Author(s)

Camille Magneville

References

Mouillot et al. (2014) Functional over-redundancy and high functional vulnerability in global fish faunas on tropical reefs. PNAS, 38, 13757-13762.

Examples

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

# Load Traits categories dataframe:
data('fruits_traits_cat', package = 'mFD')

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

# Remove continuous trait:
fruits_traits <- fruits_traits[, -5]
fruits_traits_cat <- fruits_traits_cat[-5, ]

# Compute gathering species into FEs:
sp_to_fe_fruits <- mFD::sp.to.fe(sp_tr = fruits_traits, 
 tr_cat = fruits_traits_cat, 
 fe_nm_type = 'fe_rank', check_input = TRUE)
 
# 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 alpha fd indices:
alpha.fd.fe(
   asb_sp_occ       = asb_sp_fruits_occ, 
   sp_to_fe         = sp_to_fe_fruits,
   ind_nm           = c('fred', 'fored', 'fvuln'),
   check_input      = TRUE, 
   details_returned = TRUE)

---

Illustrate Functional Diversity indices based on Functional Entities

Description

Graphical representation of distribution of species in Functional Entities (FE) and of indices from Mouillot et al. (2014). To plot functional indices, functional indices values must have been computed first through the use of the alpha.fd.fe function.

Usage

alpha.fd.fe.plot(
  alpha_fd_fe,
  plot_asb_nm,
  plot_ind_nm = c("fred", "fored", "fvuln"),
  name_file = NULL,
  color_fill_fored = "darkolivegreen2",
  color_line_fred = "darkolivegreen4",
  color_fill_bar = "grey80",
  color_fill_fvuln = "lightcoral",
  color_arrow_fvuln = "indianred4",
  size_line_fred = 1.5,
  size_arrow_fvuln = 1,
  check_input = TRUE
)

Arguments

alpha_fd_fe	output from the function alpha.fd.fe applied on assemblage of interest with details_returned = TRUE.
plot_asb_nm	a vector containing the name of the assemblage to plot.
plot_ind_nm	a vector containing the names of the indices to plot. It can be 'fred' to plot functional redundancy (FRed), 'fored' to plot functional over-redundancy (FOred) and/or 'fvuln' to plot functional vulnerability (FVuln). Default is all 3 indices.
name_file	a character string with name of file to save the figure (without extension). Default: name_file = NULL which means plot is displayed.
color_fill_fored	a R color name or an hexadecimal code referring to the color used to fill the part of barplots that contain species in excess in species-rich FEs. It refers to the FORed value. Default: color_fill_fored = "darkolivegreen2".
color_line_fred	a R color name or an hexadecimal code referring to the color used to draw the horizontal line referring to the FRed value. Default: color_line_fred = "darkolivegreen4".
color_fill_bar	a R color name or an hexadecimal code referring to the color used to draw barplots. Default: color_fill_bar = "grey80".
color_fill_fvuln	a R color name or an hexadecimal code referring to the color used to fill barplot containing only one species for illustrating FVuln. Default: color_fill_fvuln = "lightcoral".
color_arrow_fvuln	a R color name or an hexadecimal code referring to the color used to draw the horizontal arrow showing the proportion of FEs containing only one species for illustrating FVuln. If there is only one FE containing one species, the arrow will be a point. Default: color_arrow_fvuln = "indianred4".
size_line_fred	a numeric value referring to the size of the horizontal line illustrating FRed. Default: ⁠size_line_fred = 1.5.⁠
size_arrow_fvuln	a numeric value referring to the size of the arrow showing the proportion of FEs containing only one species. Default: size_arrow_fvuln = 1.
check_input	a logical value indicating whether key features the inputs are checked (e.g. class and/or mode of objects, names of rows and/or columns, missing values). If an error is detected, a detailed message is returned. Default: check_input = TRUE.

Value

A patchwork object with a barplot of number of species per FE. Indices names provided in 'plot_ind_nm' are illustrated. Functional Redundancy (average number of species per FE) is illustrated with a horizontal line. Functional Over-redundancy (proportion of species in excess in FE richer than average) is illustrated with top part of these bars filled with 'color_fill_fored'. Functional Vulnerability (proportion of FE with a single species) is illustrated with bars of these vulnerable FE filled with 'color_fill_fvuln' and the double-head arrow highlighting their number. FE-based indices values on top of the plot. if name_file is provided, plot saved as a 300dpi png file in the working directory.

Author(s)

Camille Magneville and Sebastien Villeger

References

Mouillot et al. (2014) Functional over-redundancy and high functional vulnerability in global fish faunas on tropical reefs. PNAS, 111, 13757-13762.

Examples

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

# Load Traits categories dataframe
data("fruits_traits_cat", package = "mFD")

# Load Assemblages*Species matrix
data("baskets_fruits_weights", package = "mFD")

# Remove continuous trait
fruits_traits  <- fruits_traits[ , -5]
fruits_traits_cat <- fruits_traits_cat[-5, ]

# Compute gathering species into FEs
sp_to_fe_fruits <- mFD::sp.to.fe(
  sp_tr       = fruits_traits, 
  tr_cat      = fruits_traits_cat, 
  fe_nm_type  = "fe_rank", 
  check_input = TRUE)
 
# Get the occurrence matrix
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 alpha fd indices
alpha_fd_fe_fruits <- mFD::alpha.fd.fe(
  asb_sp_occ       = asb_sp_fruits_occ, 
  sp_to_fe         = sp_to_fe_fruits,
  ind_nm           = c("fred", "fored", "fvuln"),
  check_input      = TRUE, 
  details_returned = TRUE)
  
# Plot fd fe indices
mFD::alpha.fd.fe.plot(
  alpha_fd_fe       = alpha_fd_fe_fruits, 
  plot_asb_nm       = c("basket_1"), 
  plot_ind_nm       = c("fred", "fored", "fvuln"),
  name_file         = NULL,
  color_fill_fored  = "darkolivegreen2",
  color_line_fred   = "darkolivegreen4",
  color_fill_bar    = "grey80",
  color_fill_fvuln  = "lightcoral",
  color_arrow_fvuln = "indianred4",
  size_line_fred    = 1.5,
  size_arrow_fvuln  = 1,
  check_input       = TRUE)

---

Compute Functional alpha-Diversity indices based on Hill Numbers

Description

Compute functional alpha diversity applied to distance between species following the framework from Chao et al.(2019).

Usage

alpha.fd.hill(
  asb_sp_w,
  sp_dist,
  q = c(0, 1, 2),
  tau = "mean",
  check_input = TRUE,
  details_returned = TRUE
)

Arguments

asb_sp_w	a matrix with weight of species (columns) in a set of assemblages (rows). Rows and columns should have names. NA are not allowed.
sp_dist	a matrix or dist object with distance between species. Species names should be provided and match those in 'asb_sp_w'. NA are not allowed.
q	a vector containing values referring to the order of diversity to consider, could be 0, 1 and/or 2.
tau	a character string with name of function to apply to distance matrix (i.e. among all pairs of species) to get the threshold used to define 'functionally indistinct set of species'. Could be 'mean' (default), 'min' or 'max'. If tau = 'min' and there are null values in sp_dist, the threshold is the lowest strictly positive value and a warning message is displayed.
check_input	a logical value indicating whether key features the inputs are checked (e.g. class and/or mode of objects, names of rows and/or columns, missing values). If an error is detected, a detailed message is returned. Default: check.input = TRUE.
details_returned	a logical value indicating whether the user want to store values used for computing indices (see list below)

Value

A list with:

• asb_FD_Hill a matrix containing indices values for each level of q (columns, named as 'FD_qx') for each assemblage (rows, named as in asb_sp_w)

• tau_dist the threshold value applied to distance between species to compute diversity according to function provided in tau

• if details_returned turned to TRUE a list details with

  • asb_totw a vector with total weight of each assemblage

  • asb_sp_relw a matrix with relative weight of species in assemblages

Note

FD is computed applying the special case where function 'f' in equation 3c is linear:f(dij(tau)) = dij(tau)/tau, hence f(0) = 0 and f(tau) = 1. FD computed with q=2 and tau = 'max' is equivalent to the Rao's quadratic entropy from Ricotta & Szeidl (2009, J Theor Biol). FD computed with tau = 'min' is equivalent to Hill number taxonomic diversity, thus with q=0 it is species richness (S), with q = 1 it is exponential of Shannon entropy (H) and with q = 2 it is 1/(1-D) where D is Simpson diversity. Note that even when q=0, weights of species are accounted for in FD. Hence to compute FD based only on distance between species present in an assemblage (i.e. a richness-like index) , asb_sp_w has to contain only species presence/absence coded as 0/1 with q=0 and tau = 'mean'. If asb_sp_w contains only 0/1 and q>0, it means that all species have the same contribution to FD.

Author(s)

Sebastien Villeger and Camille Magneville

References

Chao et al. (2019) An attribute diversity approach to functional diversity, functional beta diversity, and related (dis)similarity measures. Ecological Monographs, 89, e01343.

Examples

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

# Load Assemblages*Species dataframe:      
data('baskets_fruits_weights', 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 alpha fd hill indices:
alpha.fd.hill(
   asb_sp_w         = baskets_fruits_weights, 
   sp_dist          = sp_dist_fruits, 
   q                = c(0, 1, 2),
   tau              = 'mean', 
   check_input      = TRUE, 
   details_returned = TRUE)

---

Compute a set of alpha functional indices for a set of assemblages

Description

This function computes a set of multidimensional space based indices of alpha functional diversity. The user can choose which functional indices to compute.

Usage

alpha.fd.multidim(
  sp_faxes_coord,
  asb_sp_w,
  ind_vect = c("fide", "fdis", "fmpd", "fnnd", "feve", "fric", "fdiv", "fori", "fspe"),
  scaling = TRUE,
  check_input = TRUE,
  details_returned = TRUE,
  verbose = TRUE
)

Arguments

sp_faxes_coord	a matrix of species coordinates in a chosen functional space. Species coordinates have been retrieved thanks to tr.cont.fspace or quality.fspaces.
asb_sp_w	a matrix linking weight of species (columns) and a set of assemblages (rows).
ind_vect	a vector of character string of the name of functional indices to compute. Indices names must be written in lower case letters. Possible indices to compute are: 'fide', fdis', 'fmpd', 'fnnd', 'feve', 'fric', 'fdiv', 'fori' and 'fspe'. Default: all the indices are computed.
scaling	a logical value indicating if scaling is to be done (TRUE) or not (FALSE) on functional indices. Scaling is used to be able to compare indices values between assemblages. Default: scaling = TRUE.
check_input	a logical value indicating whether key features the inputs are checked (e.g. class and/or mode of objects, names of rows and/or columns, missing values). If an error is detected, a detailed message is returned. Default: check.input = TRUE.
details_returned	a logical value indicating whether the user want to store details. Details are used in graphical functions and thus must be kept if the user want to have graphical outputs for the computed indices.
verbose	a logical value indicating whether progress details should be printed in the console. If FALSE does not provide percent progress when computing diversity indices.

Value

The following list is returned:

• functional_diversity_indices matrix containing indices values (columns) for each assemblage (rows)

• details list: a asb_sp_occ data.frame of species occurrences in each assemblage ; a asb_sp_relatw matrix of relative weight of species in each assemblage ; a sp_coord_all_asb list of matrices of species coordinates along functional axes for species present in each assemblage ; a vert_nm_all_asb list of vectors of species names being vertices of the convex hull for each assemblage ; a mst_all_asb list of data.frames summarizing link between species in the minimum spanning tree of each assemblage ; a grav_center_vert_coord_all_asb list of vectors of coordinates of the vertices gravity center for each assemblage ; a mean_dtogravcenter_all_asb list of vectors containing mean distance to the species gravity center for each assemblage ; a dist_gravcenter_global_pool vector containing the distance of each species to the gravity center of all species from the global pool ; a dist_nn_global_pool data.frame showing the distances of each species from the global pool to its nearest neighbor ; a nm_nn_all_asb data.frame containing the name of each nearest neighbor of each species present in a given assemblage ; a dist_nn_all_asb data.frame containing distance of each species present in a given assemblage to its nearest neighbor.

Author(s)

Camille Magneville and Sebastien Villeger

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

# Compute alpha diversity indices
alpha_fd_indices_fruits <- mFD::alpha.fd.multidim(
  sp_faxes_coord   = sp_faxes_coord_fruits[, c('PC1', 'PC2', 'PC3', 'PC4')],
  asb_sp_w         = baskets_fruits_weights, 
  ind_vect         = c('fdis', 'fmpd', 'fnnd', 'feve', 'fric', 'fdiv', 
                       'fori', 'fspe'),
  scaling          = TRUE, 
  check_input      = TRUE, 
  details_returned = TRUE)
  
# Retrieve alpha diversity indices table
fd_ind_values_fruits <- alpha_fd_indices_fruits$functional_diversity_indices
fd_ind_values_fruits

---

Plot functional space and chosen functional indices

Description

Compute a graphical representation of functional indices. To plot functional indices, functional indices values must have been retrieve through the use of the alpha.fd.multidim function.

Usage

alpha.multidim.plot(
  output_alpha_fd_multidim,
  plot_asb_nm,
  ind_nm = c("fide", "fric", "fdiv", "fdis", "feve", "fori", "fspe", "fnnd"),
  faxes = NULL,
  faxes_nm = NULL,
  range_faxes = c(NA, NA),
  color_bg = "grey95",
  shape_sp = c(pool = 3, asb1 = 21, asb2 = 21),
  size_sp = c(pool = 0.7, asb1 = 1, asb2 = 1),
  color_sp = c(pool = "grey50", asb1 = "#0072B2", asb2 = "#D55E00"),
  color_vert = c(pool = "grey50", asb1 = "#0072B2", asb2 = "#D55E00"),
  fill_sp = c(pool = NA, asb1 = "#FFFFFF30", asb2 = "#FFFFFF30"),
  fill_vert = c(pool = NA, asb1 = "#0072B2", asb2 = "#D55E00"),
  color_ch = c(pool = NA, asb1 = "#0072B2", asb2 = "#D55E00"),
  fill_ch = c(pool = "white", asb1 = "#0072B2", asb2 = "#D55E00"),
  alpha_ch = c(pool = 1, asb1 = 0.3, asb2 = 0.3),
  shape_centroid_fdis = c(asb1 = 22, asb2 = 22),
  shape_centroid_fdiv = c(asb1 = 24, asb2 = 25),
  shape_centroid_fspe = 23,
  color_centroid_fspe = "black",
  size_sp_nm = 3,
  color_sp_nm = "black",
  plot_sp_nm = NULL,
  fontface_sp_nm = "plain",
  save_file = FALSE,
  check_input = TRUE
)

Arguments

output_alpha_fd_multidim	a list of objects retrieved through the alpha.fd.multidim function.
plot_asb_nm	a vector containing name(s) of assemblage(s) to plot.
ind_nm	a vector of character string of the name of functional indices to plot. Indices names must be written in lower case letters. Possible indices to compute are: "fdis", "feve", "fric", "fdiv", "fori" and "fspe". Default: all the indices are computed.
faxes	a vector with names of axes to plot. You can only plot from 2 to 4 axes for graphical reasons: vector length should be between 2 and 4. Default: faxes = NULL (the four first axes will be plotted).
faxes_nm	a vector with axes labels if the user want different axes labels than faxes ones. Default: faxes_nm = faxes (labels will the the same that faxes ones).
range_faxes	a vector with minimum and maximum for values for axes. Note that to have a fair representation of position of species in all plots, all axes must have the same range. Default: faxes_lim = c(NA, NA) (the range is computed according to the range of values among all axes, all axes having the same range).
color_bg	a R color name or an hexadecimal code used to fill plot background. Default: color_bg = "grey95".
shape_sp	a vector gathering numeric values referring to the symbol used to draw species from the global pool and the plotted assemblage(s). It should be written as c(pool = "...", asb1 = "...", ...). (0 = high transparency, 1 = no transparency).
size_sp	a vector gathering numeric values referring to the size of species belonging to the global pool and the plotted assemblage(s). It should be written as c(pool = "...", asb1 = "...", ...).
color_sp	a vector gathering R color names or hexadecimal codes referring to the color of species from the global pool and studied assemblage(s). It should be written as c(pool = "...", asb1 = "...", ...).
color_vert	a vector gathering R color names or hexadecimal codes referring to the color of vertices from the global pool and studied assemblage(s). It should be written as c(pool = "...", asb1 = "...", ...).
fill_sp	a vector gathering R color names or hexadecimal codes referring to the filled color of species from the global pool and studied assemblage(s). It should be written as c(pool = "...", asb1 = "...", ...).
fill_vert	a vector gathering R color names or hexadecimal codes referring to the filled color of vertices from the global pool and studied assemblage(s). It should be written as c(pool = "...", asb1 = "...", ...).
color_ch	a vector gathering R color names or hexadecimal codes referring to the color of the convex pool of the global pool and studied assemblage(s). It should be written as c(pool = "...", asb1 = "...", ...).
fill_ch	a vector gathering R color names or hexadecimal codes referring to the color to fill the convex pool of the global pool and studied assemblage(s). It should be written as c(pool = "...", asb1 = "...", ...).
alpha_ch	a vector gathering numeric values referring to the opacity of convex hulls of the global pool and the plotted assemblage(s). It should be written as c(pool = "...", asb1 = "...", ...). (0 = high transparency, 1 = no transparency).
shape_centroid_fdis	a vector gathering numeric value(s) used to draw FDis centroid size.
shape_centroid_fdiv	a vector gathering numeric value(s) used to draw FDiv centroid size.
shape_centroid_fspe	a vector gathering numeric value used to draw FSpe centroid (i.e. center of the functional space) size.
color_centroid_fspe	a vector gathering R color name or hexadecimal code used to draw FSpe centroid (i.e. center of the functional space) color.
size_sp_nm	a numeric value referring to the size of species names if plotted.
color_sp_nm	a R color name or hexadecimal code referring to the color of names of species if plotted.
plot_sp_nm	a vector containing species names that are to be plotted. Default: plot_nm_sp = NULL (no name plotted).
fontface_sp_nm	a character string for font of species labels (e.g. "italic", "bold"). Default: fontface_sp_nm = 'plain'.
save_file	a logical value telling if plots should be locally saved or not.
check_input	a logical value indicating whether key features the inputs are checked (e.g. class and/or mode of objects, names of rows and/or columns, missing values). If an error is detected, a detailed message is returned. Default: check.input = TRUE.

Value

If name_file is NULL, it returns a list of one ggplot2 plots per functional index containing plots for combinations of up to four axes, a patchwork figure gathering all combinations of axes and a ggplot2 figure showing the plot caption. If name_file is not NULL, then those plots are saved locally.

Author(s)

Camille Magneville and Sebastien Villeger

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)

# 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

# Compute alpha diversity indices:
alpha_fd_indices_fruits <- mFD::alpha.fd.multidim(
  sp_faxes_coord   = sp_faxes_coord_fruits[, c("PC1", "PC2", "PC3", "PC4")],
  asb_sp_w         = baskets_fruits_weights,
  ind_vect         = c("fdis", "fmpd", "fnnd", "feve", "fric", "fdiv",
                       "fori", "fspe"),
  scaling          = TRUE,
  check_input      = TRUE,
  details_returned = TRUE)

# Plot all fd alpha indices:
plots_alpha <- mFD::alpha.multidim.plot(
output_alpha_fd_multidim = alpha_fd_indices_fruits,
plot_asb_nm              = c("basket_1", "basket_5"),
ind_nm                   = c("fdis", "fide", "fnnd", "feve", 
                             "fric", "fdiv", "fori", 
                             "fspe"),
faxes                    = NULL,
faxes_nm                 = NULL,
range_faxes              = c(NA, NA),
color_bg                 = "grey95",
shape_sp                 = c(pool = 3, asb1 = 21, 
                             asb2 = 21),
size_sp                  = c(pool = 0.7, asb1 = 1, 
                             asb2 = 1),
color_sp                 = c(pool = "grey50", 
                             asb1 = "#1F968BFF",
                             asb2 = "#DCE319FF"),
color_vert               = c(pool = "grey50", 
                             asb1 = "#1F968BFF",
                             asb2 = "#DCE319FF"),
fill_sp                 = c(pool =  NA, 
                            asb1 = "#1F968BFF",
                            asb2 = "#DCE319FF"),
fill_vert               = c(pool = NA, 
                            asb1 = "#1F968BFF",
                            asb2 = "#DCE319FF"),
color_ch                = c(pool = NA, 
                            asb1 = "#1F968BFF",
                            asb2 = "#DCE319FF"),
fill_ch                 = c(pool = "white", 
                            asb1 = "#1F968BFF",
                            asb2 = "#DCE319FF"),
alpha_ch                = c(pool = 1, asb1 = 0.3, 
                            asb2 = 0.3),
shape_centroid_fdis     = c(asb1 = 22,  asb2 = 24),
shape_centroid_fdiv     = c(asb1 = 22,  asb2 = 24),
shape_centroid_fspe     = 23,
color_centroid_fspe     = "black",
size_sp_nm              = 3, 
color_sp_nm             = "black",
plot_sp_nm              = NULL,
fontface_sp_nm          = "plain",
save_file               = FALSE,
check_input             = TRUE) 

# Check FRic plot:
plots_alpha$fric$patchwork

---

Summarize Assemblage x Species data frame

Description

This function computes a summary helping you to picture assemblages. For this function to work, there must be no NA in your asb_sp_w data frame.

Usage

asb.sp.summary(asb_sp_w)

Arguments

asb_sp_w

a matrix showing assemblages (rows) composition in species (columns). Note that species names must be the names of rows.

Value

A list with:

asb_sp_w_occ	a matrix with species occurrences in each assemblage.
sp_tot_w	a vector gathering species biomass/abundance per species.
asb_tot_w	a vector gathering total abundance/biomass per assemblage.
asb_sp_richn	a vector gathering species richness per assemblage.
asb_sp_nm	a list gathering the names of species of each assemblage.

Author(s)

Camille Magneville and Sebastien Villeger

Examples

# Load Assemblages x Species Matrix
data('baskets_fruits_weights', package = 'mFD')

# Summarize Assemblages Data
mFD::asb.sp.summary(asb_sp_w = baskets_fruits_weights)

---

Plot background of multidimensional plots

Description

This function creates a ggplot object with customized axes range (same for both), names and background

Usage

background.plot(range_faxes, faxes_nm, color_bg)

Arguments

range_faxes	a vector with minimum and maximum values of axes. Note that to have a fair representation of position of species in all plots, they should have the same range. Default: range_faxes = c(NA, NA) (the range is computed according to the range of values among all axes).
faxes_nm	a vector with axes labels for figure.
color_bg	a R color name or an hexadecimal code used to fill plot background. Default: color_bg = "grey95".

Value

A ggplot object plotting background of multidimensional graphs.

Author(s)

Camille Magneville and Sebastien Villeger

Examples

background <- background.plot(range_faxes = c(-1, 2), 
                               faxes_nm    = c("PC 1", "PC 2"), 
                               color_bg    = "grey90")
 background

---

Dataset: Baskets Composition in Fruits Species

Description

This dataset represents the abundance of 25 fruits species in 10 baskets.

Usage

baskets_fruits_weights

Format

A matrix of integers with 10 rows (baskets) and 25 columns (species).

See Also

fruits_traits, fruits_traits_cat

Examples

## Not run: 
# Load Assemblages x Species Matrix
data("baskets_fruits_weights", package = "mFD")
baskets_fruits_weights[1:5, 1:5]

# Summarize Assemblages Data
mFD::asb.sp.summary(asb_sp_w = baskets_fruits_weights)

## End(Not run)

---

Compute Functional beta-Diversity indices based on Hill Numbers

Description

Compute functional beta-diversity indices based on Hill numbers applied to distance between species following the framework from Chao et al. (2019).

Usage

beta.fd.hill(
  asb_sp_w,
  sp_dist,
  q = c(0, 1, 2),
  tau = "mean",
  beta_type = "Jaccard",
  check_input = TRUE,
  details_returned = TRUE
)

Arguments

asb_sp_w	a matrix with weight of species (columns) in a set of assemblages (rows). Rows and columns should have names. NA are not allowed.
sp_dist	a matrix or dist object with distance between species. Species names should be provided and match those in 'asb_sp_w'. NA are not allowed.
q	a vector containing values referring to the order of diversity to use
tau	a character string with name of function to apply to distance matrix (i.e. among all pairs of species) to get the threshold used to define 'functionally indistinct set of species'. Could be qet to 'mean' (default), 'min' or 'max'.
beta_type	a character string with name of framework used for computing beta-diversity, either 'Jaccard' (default) or 'Sorensen'.
check_input	a logical value indicating whether key features the inputs are checked (e.g. class and/or mode of objects, names of rows and/or columns, missing values). If an error is detected, a detailed message is returned. Default: check_input = TRUE.
details_returned	a logical value indicating whether the user want to store values used for computing indices (see list below)

Value

A list with:

• asb_FDbeta a list with for each value of q a dist object with beta functional diversity indices for all pairs of assemblages item if store.details turned to TRUE a list details with

  • malpha_fd_q a list with for each value of q a dist object with mean alpha functional diversity indices for all pairs of assemblages

  • gamma_fd_q a list with for each value of q a dist object with gamma functional diversity indices for all pairs of assemblages

Note

When q=1 Jaccard-like and Sorensen-like beta-diversity are identical. FD computed with tau='min' is equivalent to Hill number taxonomic beta diversity. If tau='min' and there are species with null distance, tau is set to the minimum non-null value and a warning message is displayed. 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

Author(s)

Sebastien Villeger and Camille Magneville

References

Chao et al. (2019) An attribute diversity approach to functional diversity, functional beta diversity, and related (dis)similarity measures. Ecological Monographs, 89, e01343.

Examples

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

# Load Traits types 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 beta functional hill indices:
baskets_beta <- beta.fd.hill(
      asb_sp_w         = baskets_fruits_weights, 
      sp_dist          = sp_dist_fruits, 
      q                = c(0,1,2), 
      tau              = 'mean',
      beta_type        = 'Jaccard', 
      check_input      = TRUE, 
      details_returned = TRUE)
 
# Then use the mFD::dist.to.df function to ease visualizing result:
## for q = 0:
mFD::dist.to.df(list_dist = list(FDq2 = baskets_beta$beta_fd_q$q0))
## for q = 1:
mFD::dist.to.df(list_dist = list(FDq2 = baskets_beta$beta_fd_q$q1))
## for q = 2:
mFD::dist.to.df(list_dist = list(FDq2 = baskets_beta$beta_fd_q$q2))

---

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

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.

Author(s)

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

## Not run: 
 # 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)

## End(Not run)

---

Illustrate Functional beta-Diversity indices for pairs of assemblages in a multidimensional space

Description

Illustrate overlap between convex hulls shaping species assemblages in a multidimensional functional space.Before plotting beta functional diversity indices should have been computed using the beta.fd.multidim function.

Usage

beta.multidim.plot(
  output_beta_fd_multidim,
  plot_asb_nm,
  beta_family,
  plot_sp_nm = NULL,
  faxes = NULL,
  name_file = NULL,
  faxes_nm = NULL,
  range_faxes = c(NA, NA),
  color_bg = "grey95",
  shape_sp = c(pool = 3, asb1 = 22, asb2 = 21),
  size_sp = c(pool = 0.7, asb1 = 1.2, asb2 = 1),
  color_sp = c(pool = "grey50", asb1 = "blue", asb2 = "red"),
  fill_sp = c(pool = NA, asb1 = "white", asb2 = "white"),
  fill_vert = c(pool = NA, asb1 = "blue", asb2 = "red"),
  color_ch = c(pool = NA, asb1 = "blue", asb2 = "red"),
  fill_ch = c(pool = "white", asb1 = "blue", asb2 = "red"),
  alpha_ch = c(pool = 1, asb1 = 0.3, asb2 = 0.3),
  nm_size = 3,
  nm_color = "black",
  nm_fontface = "plain",
  check_input = TRUE
)

Arguments

output_beta_fd_multidim	the list returned by beta.fd.multidim when details_returned = TRUE. Thus, even if this function will illustrate functional beta-diversity for a single pair of assemblages, plots will be scaled according to all assemblages for which indices were computed.
plot_asb_nm	a vector with names of the 2 assemblages for which functional beta-diversity will be illustrated.
beta_family	a character string for the type of beta-diversity index for which values will be printed, 'Jaccard' (default) and/or 'Sorensen'.
plot_sp_nm	a vector containing species names that are to be plotted. Default: plot_nm_sp = NULL (no name plotted).
faxes	a vector with names of axes to plot (as columns names in output_beta_fd_multidim$details$input$sp_faxes_coord ). You can only plot from 2 to 4 axes for graphical reasons. Default: faxes = NULL (the four first axes will be plotted).
name_file	a character string with name of file to save the figure (without extension). Default: name_file = NULL which means plot is displayed.
faxes_nm	a vector with axes labels for figure. Default: as faxes).
range_faxes	a vector with minimum and maximum values of axes. Note that to have a fair representation of position of species in all plots, they should have the same range. Default: faxes_lim = c(NA, NA) (the range is computed according to the range of values among all axes).
color_bg	a R color name or an hexadecimal code used to fill plot background. Default: color_bg = "grey95".
shape_sp	a vector with 3 numeric values referring to the shape of symbol used for species from the 'pool' absent from the 2 assemblages, and for species present in the 2 assemblages ('asb1', and 'asb2'), respectively. Default: shape_sp = c(pool = 3, asb1 = 22, asb2 = 21) so cross, square and circle.
size_sp	a numeric value referring to the size of symbols for species. Default: ⁠is size_sp = c(pool = 0.8, asb1 = 1, asb2 = 1)⁠.
color_sp	a vector with 3 names or hexadecimal codes referring to the colour of symbol for species. Default is: color_sp = c(pool = "grey50", asb1 = "blue", asb2 = "red").
fill_sp	a vector with 3 names or hexadecimal codes referring to the color to fill symbol (if shape_sp > 20) for species of the pool and of the 2 assemblages. Default is: fill_sp = c(pool = NA, asb1 = "white", asb2 = "white").
fill_vert	a vector with 3 names or hexadecimal codes referring to the colour to fill symbol (if shape_sp > 20) for species being vertices of the convex hulls of the pool of species and of the 2 assemblages. Default is: fill_vert = c(pool = NA, asb1 = "blue", asb2 = "red").
color_ch	a vector with 3 names or hexadecimal codes referring to the border of the convex hulls of the pool of species and by the 2 assemblages. Default is: color_ch = c(pool = NA, asb1 = "blue", asb2 = "red").
fill_ch	a vector with 3 names or hexadecimal codes referring to the filling of the convex hull of the pool of species and of the 2 assemblages. Default is fill_ch = c(pool = "white", asb1 = "blue", asb2 = "red").
alpha_ch	a vector with 3 numeric value for transparency of the filling of the convex hulls (0 = high transparency, 1 = no transparency). Default is: alpha_ch = c(pool = 1, asb1 = 0.3, asb2 = 0.3).
nm_size	a numeric value for size of species label. Default is 3 (in points).
nm_color	a R color name or an hexadecimal code referring to the color of species label. Default is black.
nm_fontface	a character string for font of species labels (e.g. "italic", "bold"). Default is 'plain'.
check_input	a logical value indicating whether key features the inputs are checked (e.g. class and/or mode of objects, names of rows and/or columns, missing values). If an error is detected, a detailed message is returned. Default: check.input = TRUE.

Value

If name_file is NULL, it returns a patchwork figure with overlap between convex hulls projected in 2-dimensional spaces for the given pair of assemblages. Values of functional beta-diversity indices are shown on top-right corner of the figure. If name_file is not NULL, the plot is saved locally.

Author(s)

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)

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

# Compute beta fd plots:
 beta.multidim.plot(
   output_beta_fd_multidim = beta_fd_fruits,
   plot_asb_nm             = c("basket_1", "basket_6"),
   beta_family             = c("Jaccard"),
   plot_sp_nm              = c("apple", "cherry", "lemon"),
   faxes                   = paste0("PC", 1:4),
   name_file               = NULL,
   faxes_nm                = NULL,
   range_faxes             = c(NA, NA),
   color_bg                = "grey95",
   shape_sp                = c(pool = 3, asb1 = 22, asb2 = 21),
   size_sp                 = c(pool = 0.8, asb1 = 1, asb2 = 1),
   color_sp                = c(pool = "grey50", asb1 = "blue",
                               asb2 = "red"),
   fill_sp                 = c(pool = NA, asb1 = "white", asb2 = "white"),
   fill_vert               = c(pool = NA, asb1 = "blue", asb2 = "red"),
   color_ch                = c(pool = NA, asb1 = "blue", asb2 = "red"),
   fill_ch                 = c(pool = "white", asb1 = "blue",
                               asb2 = "red"),
   alpha_ch                = c(pool = 1, asb1 = 0.3, asb2 = 0.3),
   nm_size                 = 3,
   nm_color                = "black",
   nm_fontface             = "plain",
   check_input             = TRUE)

---

Compute distance of a given point to its nearest neighbor in the functional space and the identity of the nearest neighbor

Description

This function is used in functional indices computation.

Usage

dist.nearneighb(sp_faxes_coord, ref_sp)

Arguments

sp_faxes_coord	a matrix of species coordinates in a chosen functional space. Species coordinates have been retrieved thanks to tr.cont.fspace or quality.fspaces.
ref_sp	a character string referring to the name of the reference species.

Value

A list containing the nearest neighbor identity nn_id and a list of the distance of the reference point to its nearest neighbor nn_ref_sp_dist.

Author(s)

Camille Magneville and Sebastien Villeger

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

# Compute the distance of "pear" to its nearest neighbor(s):
 dist_nn_pear <- dist.nearneighb(sp_faxes_coord_fruits, ref_sp = "pear")
 dist_nn_pear

---

Compute distances of all points to a given point in the functional space

Description

This function computes the distances of all species to a reference species. It is used in FSpe, FOri and FNND computation.

Usage

dist.point(sp_faxes_coord, ref_sp)

Arguments

sp_faxes_coord	a matrix of species coordinates in a chosen functional space. Species coordinates have been retrieved thanks to tr.cont.fspace or quality.fspaces.
ref_sp	a character string referring to the name of the reference species.

Value

A vector of species distances to the reference species.

Author(s)

Camille Magneville and Sebastien Villeger

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

# Retrieve the distances of all species to "pear":
 dist_pear <- dist.point(sp_faxes_coord_fruits, ref_sp = "pear")
 dist_pear

---

Merge distance object(s) into a single data frame

Description

This function merges distance object(s) into a single data frame which rows are pairs of elements and column(s) distance metric(s). It stands on the dist_long function.

Usage

dist.to.df(list_dist)

Arguments

list_dist

a list of dist object(s). All dist objects should have a name (e.g. name of distance metric) and the same labels (i.e. names of sets between which distance was computed).

Value

A data frame which first and second columns (names x1 and x2) contain names of the 2 sets involved in each pair, and with one column for each dist object (named after its name in list_dist.

Author(s)

Sebastien Villeger

Examples

# Create dist objects: 
dist_A <- round(dist(matrix(runif(10, 0, 1), 5, 2, 
                      dimnames = list(letters[1:5], NULL))), 2)
dist_B <- round(dist(matrix(runif(10, 0, 1), 5, 2, 
                      dimnames = list(letters[1:5], NULL))), 2)
dist_C <- round(dist(matrix(runif(10, 0, 1), 5, 2, 
                      dimnames = list(letters[1:5], NULL))), 2)

# First example with only 1 distance:
dist.to.df(list(dA = dist_A))

# Second example with 3 distances:
dist.to.df(list(d1 = dist_A, d2 = dist_B, d3 = dist_C))

---

Plot FDis index

Description

This function plots FDis index for a given pair of functional axes and for one or several assemblages. It adds segments between species relative weights and assemblage cenntroid on the background plot.

Usage

fdis.plot(
  ggplot_bg,
  asb_sp_coord2D,
  asb_sp_relatw,
  asb_fide_coord2D,
  plot_sp = TRUE,
  shape_sp,
  color_sp,
  fill_sp,
  shape_fide,
  size_fide,
  color_fide,
  fill_fide,
  color_segment,
  width_segment,
  linetype_segment
)

Arguments

ggplot_bg	a ggplot object of the plot background retrieved through the background.plot function.
asb_sp_coord2D	a list of matrix (ncol = 2) with coordinates of species present in each assemblage for a given pair of functional axes.
asb_sp_relatw	a list of vector gathering species relative weight in each assemblage. It can be retrieved through the alpha.fd.multidim.
asb_fide_coord2D	a list (with names as in asb_sp_coord2D) of vectors with coordinates of the fide centroid of species for each assemblage for a given pair of axes.
plot_sp	a logical value indicating whether species of each assemblage should be plotted or not. Default: plot_sp = TRUE
shape_sp	a numeric value referring to the shape of the symbol used for species plotting if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRshape", asb2 = "secondRshape", ...).
color_sp	a R color name or an hexadecimal code referring to the color of species if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
fill_sp	a R color name or an hexadecimal code referring to the color of species symbol filling (if shape_sp > 20) if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
shape_fide	a numeric value referring to the shape of the symbol used for fide centroid if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRshape", asb2 = "secondRshape", ...).
size_fide	a numeric value referring to the size of the symbol used for fide centroid plotting if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRsize", asb2 = "secondRsize", ...).
color_fide	a R color name or an hexadecimal code referring to the color of fide centroid if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
fill_fide	a R color name or an hexadecimal code referring to the color to fill assemblage centroid symbol (if shape_sp > 20) if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
color_segment	a R color name or an hexadecimal code referring to the color of of the segment linking axes and centroid from the studied assemblage if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
width_segment	a numeric value referring to the width of the segment linking fide centroid and functional axes if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRsize", asb2 = "secondRsize", ...).
linetype_segment	a numeric value referring to the linetype of the segment linking fide centroid and functional axes if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRlinetype", asb2 = "secondRlinetype", ...).

Value

A ggplot object showing FDis index for one or several assemblage(s) and a given pair of functional axes.

Author(s)

Camille Magneville and Sebastien Villeger

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

# Set faxes limits:
# set range of axes if c(NA, NA):
 range_sp_coord_fruits  <- range(sp_faxes_coord_fruits)
 range_faxes_lim <- range_sp_coord_fruits + 
 c(-1, 1)*(range_sp_coord_fruits[2] - 
 range_sp_coord_fruits[1]) * 0.05
 
 # Retrieve the background plot:
 ggplot_bg_fruits <- mFD::background.plot(
                               range_faxes = range_faxes_lim, 
                               faxes_nm    = c("PC 1", "PC 2"), 
                               color_bg    = "grey90") 
                               
 # Retrieve the matrix of species coordinates for "basket_1" and PC1 and PC2
 sp_filter <- mFD::sp.filter(asb_nm         = "basket_1", 
                             sp_faxes_coord = sp_faxes_coord_fruits, 
                             asb_sp_w       = baskets_fruits_weights)
 fruits_asb_sp_coord_b1 <- sp_filter$`species coordinates`
 fruits_asb_sp_coord2D_b1 <- fruits_asb_sp_coord_b1[, c("PC1", "PC2")]
                               
 # Use alpha.fd.multidim() function to get inputs to plot FIde:
 alpha_fd_indices_fruits <- mFD::alpha.fd.multidim(
 sp_faxes_coord    = sp_faxes_coord_fruits[, c("PC1", "PC2", "PC3", "PC4")],
  asb_sp_w         = baskets_fruits_weights,
  ind_vect         = c("fdis"),
  scaling          = TRUE,
  check_input      = TRUE,
  details_returned = TRUE)
  
 # Retrieve fide values through alpha.fd.multidim outputs:
 fruits_asb_fide_coord2D <- 
  alpha_fd_indices_fruits$functional_diversity_indices[c("fide_PC1", 
                                                         "fide_PC2")]
 fruits_asb_fide_coord2D_b1 <- fruits_asb_fide_coord2D[c("basket_1"), ]
 fruits_asb_sp_relatw_b1 <- 
         alpha_fd_indices_fruits$details$asb_sp_relatw["basket_1", ]

 # Retrieve FDis plot:
 fdis_plot <- fdis.plot(ggplot_bg = ggplot_bg_fruits,
           asb_sp_coord2D = list(basket_1 = fruits_asb_sp_coord2D_b1),
           asb_sp_relatw = list(basket_1 = fruits_asb_sp_relatw_b1),
           asb_fide_coord2D = list(basket_1 = fruits_asb_fide_coord2D_b1),
           plot_sp = TRUE,
           shape_sp = 16,
           color_sp = "red",
           fill_sp = "red",
           shape_fide = list(basket_1 = 18),
           size_fide = list(basket_1 = 5),
           color_fide = list(basket_1 = "blue"),
           fill_fide = list(basket_1 = "blue"),
           color_segment = list(basket_1 = "red"),
           width_segment = list(basket_1 = 1),
           linetype_segment = list(basket_1 = "dashed"))
           
 fdis_plot

---

Plot FDiv indice

Description

This plot fDiv indice for a given pair of functional axes and one or several assemblages. This function adds mean distance to center of gravity of vertices, points and vertices of 1:N assemblages on the background plot

Usage

fdiv.plot(
  ggplot_bg,
  asb_sp_coord2D,
  asb_sp_relatw,
  asb_vertices_nD,
  asb_vertG_coord2D,
  plot_sp = TRUE,
  shape_sp,
  color_sp,
  fill_sp,
  shape_vert,
  color_vert,
  fill_vert,
  shape_vertG,
  size_vertG,
  color_vertG,
  fill_vertG
)

Arguments

ggplot_bg	a ggplot object of the plot background retrieved through the background.plot function.
asb_sp_coord2D	a list of matrix (ncol = 2) with coordinates of species present in each assemblage for a given pair of functional axes.
asb_sp_relatw	a list of vector gathering species relative weight in each assemblage. It can be retrieved through the alpha.fd.multidim.
asb_vertices_nD	a list (with names as in asb_sp_coord2D) of vectors with names of species being vertices in n dimensions.
asb_vertG_coord2D	a list (with names as in asb_sp_coord2D) containing for each assemblage the coordinates of center of gravity of vertices for a given pair of axes
plot_sp	a logical value indicating whether species of each assemblage should be plotted or not. Default: plot_sp = TRUE.
shape_sp	a numeric value referring to the shape of the symbol used for species plotting if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRshape", asb2 = "secondRshape", ...).
color_sp	a R color name or an hexadecimal code referring to the color of species if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
fill_sp	a R color name or an hexadecimal code referring to the color of species symbol filling (if shape_sp > 20) if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
shape_vert	a numeric value referring to the shape of the symbol used for vertices plotting if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRshape", asb2 = "secondRshape", ...).
color_vert	a R color name or an hexadecimal code referring to the color of vertices if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...). If color_vert = NA, vertices are not plotted (for shapes only defined by color, ie shape inferior to 20. Otherwise fill must also be set to NA).
fill_vert	a R color name or an hexadecimal code referring to the color of vertices symbol filling (if shape_vert >20) if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...). If fill = NA and color = NA, vertices are not plotted (if shape_vert superior to 20
shape_vertG	a numeric value referring to the shape to use to plot the center of gravity of vertices if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRshape", asb2 = "secondRshape", ...).
size_vertG	a numeric value referring to the size of the symbol used for the center of gravity of vertices if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRsize", asb2 = "secondRsize", ...).
color_vertG	a R color name or an hexadecimal code referring to the color of the center of gravity of vertices. if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
fill_vertG	a R color name or an hexadecimal code referring to the color to fill the center of gravity of vertices (if shape_vert >20) if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).

Value

A ggplot object plotting background of multidimensional graphs and FDiv indice.

Author(s)

Camille Magneville and Sebastien Villeger

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

# Set faxes limits:
# set range of axes if c(NA, NA):
 range_sp_coord_fruits  <- range(sp_faxes_coord_fruits)
 range_faxes_lim <- range_sp_coord_fruits + 
 c(-1, 1)*(range_sp_coord_fruits[2] - 
 range_sp_coord_fruits[1]) * 0.05
 
 # Retrieve the background plot:
 ggplot_bg_fruits <- mFD::background.plot(
                               range_faxes = range_faxes_lim, 
                               faxes_nm    = c("PC 1", "PC 2"), 
                               color_bg    = "grey90") 
                               
 # Retrieve the matrix of species coordinates for "basket_1" and PC1 and PC2
 sp_filter <- mFD::sp.filter(asb_nm          = "basket_1", 
                             sp_faxes_coord = sp_faxes_coord_fruits, 
                             asb_sp_w       = baskets_fruits_weights)
 fruits_asb_sp_coord_b1 <- sp_filter$`species coordinates`
 fruits_asb_sp_coord2D_b1 <- fruits_asb_sp_coord_b1[, c("PC1", "PC2")]
                               
 # Use alpha.fd.multidim() function to get inputs to plot FDiv:
 alpha_fd_ind <- mFD::alpha.fd.multidim(
sp_faxes_coord   = sp_faxes_coord_fruits[ , c("PC1", "PC2", "PC3", "PC4")],
asb_sp_w         = baskets_fruits_weights,
ind_vect         = c("fdiv"),
scaling          = TRUE,
check_input      = TRUE,
details_returned = TRUE)
  
 # Retrieve inputs of the fdiv.plot() function for "basket_1" and PC1, PC2
 # ... through alpha.fd.multidim outputs:
 fruits_asb_sp_relatw_b1 <- 
         alpha_fd_ind$details$asb_sp_relatw["basket_1", ]
 fruits_asb_vertices_nD_b1_2D <- 
                     alpha_fd_ind$details$asb_vert_nm["basket_1"]
 fruits_asb_vertG_coord_b1 <- 
                     alpha_fd_ind$details$asb_G_coord["basket_1"]
 fruits_asb_vertG_coord_b1_2D <- 
             fruits_asb_vertG_coord_b1[[1]][c("PC1", "PC2")]
 
 # Retrieve FDiv plot:
 fdiv_plot <- fdiv.plot(
           ggplot_bg         = ggplot_bg_fruits,
           asb_sp_coord2D    = list(basket_1 = fruits_asb_sp_coord2D_b1),
           asb_sp_relatw     = list(basket_1 = fruits_asb_sp_relatw_b1),
           asb_vertices_nD   = fruits_asb_vertices_nD_b1_2D,
           asb_vertG_coord2D = list(basket_1 = fruits_asb_vertG_coord_b1_2D),
           plot_sp           = TRUE,
           shape_sp          = 16,
           color_sp          = c(basket_1 = "red"),
           fill_sp           = "red",
           color_vert        = "red",
           fill_vert         = "red",
           shape_vert        = 16,
           shape_vertG       = list(basket_1 = 18),
           size_vertG        = list(basket_1 = 2),
           color_vertG       = list(basket_1 = "blue"),
           fill_vertG        = list(basket_1 = "blue"))
 fdiv_plot

---

Plot FEve index

Description

This function plots FEve index for a given pair of functional axes and one or several assemblages. It adds Minimum Spanning Tree (MST) of a given assemblage on the background plot.

Usage

feve.plot(
  ggplot_bg,
  asb_sp_coord2D,
  asb_sp_relatw,
  asb_mst,
  plot_sp = TRUE,
  shape_sp,
  color_sp,
  fill_sp,
  color_mst,
  width_mst,
  linetype_mst
)

Arguments

ggplot_bg	a ggplot object of the plot background retrieved through the background.plot function.
asb_sp_coord2D	a list of matrix (ncol = 2) with coordinates of species present in each assemblage for a given pair of functional axes.
asb_sp_relatw	a list of vector gathering species relative weight in each assemblage. It can be retrieved through the alpha.fd.multidim.
asb_mst	a list (with names as in asb_sp_coord2D) of vectors with names of species linked in the MST of the studied assemblage.
plot_sp	a logical value indicating whether species of each assemblage should be plotted or not. Default: plot_sp = TRUE
shape_sp	a numeric value referring to the shape of the symbol used for species plotting if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRshape", asb2 = "secondRshape", ...).
color_sp	a R color name or an hexadecimal code referring to the color of species if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
fill_sp	a R color name or an hexadecimal code referring to the color of species symbol filling (if shape_sp > 20) if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
color_mst	a R color name or an hexadecimal code referring to the color the MST if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
width_mst	a numeric value referring to the width of segments of the MST if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRsize", asb2 = "secondRsize", ...).
linetype_mst	a numeric value referring to the linetype of the segments representing the MST if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRlinetype", asb2 = "secondRlinetype", ...).

Value

A ggplot object showing FEve index on the background plot.

Author(s)

Camille Magneville and Sebastien Villeger

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

# Set faxes limits:
# set range of axes if c(NA, NA):
 range_sp_coord_fruits  <- range(sp_faxes_coord_fruits)
 range_faxes_lim <- range_sp_coord_fruits + 
 c(-1, 1)*(range_sp_coord_fruits[2] - 
 range_sp_coord_fruits[1]) * 0.05
 
 # Retrieve the background plot:
 ggplot_bg_fruits <- mFD::background.plot(
                               range_faxes = range_faxes_lim, 
                               faxes_nm    = c("PC 1", "PC 2"), 
                               color_bg    = "grey90") 
                               
 # Retrieve the matrix of species coordinates for "basket_1" and PC1 and PC2
 sp_filter <- mFD::sp.filter(asb_nm          = "basket_1", 
                             sp_faxes_coord = sp_faxes_coord_fruits, 
                             asb_sp_w       = baskets_fruits_weights)
 fruits_asb_sp_coord_b1 <- sp_filter$`species coordinates`
 fruits_asb_sp_coord2D_b1 <- fruits_asb_sp_coord_b1[, c("PC1", "PC2")]
                               
 # Use alpha.fd.multidim() function to get inputs to plot FIde:
 alpha_fd_indices_fruits <- mFD::alpha.fd.multidim(
  sp_faxes_coord   = sp_faxes_coord_fruits[, c("PC1", "PC2", "PC3", "PC4")],
  asb_sp_w         = baskets_fruits_weights,
  ind_vect         = c("feve"),
  scaling          = TRUE,
  check_input      = TRUE,
  details_returned = TRUE)
  
 # Retrieve fide values through alpha.fd.multidim outputs:
 fruits_asb_mst_b1 <- 
         alpha_fd_indices_fruits$details$asb_mst["basket_1"]
 fruits_asb_sp_coord_b1 <- sp_filter$`species coordinates`
 fruits_asb_sp_coord2D_b1 <- fruits_asb_sp_coord_b1[, c("PC1", "PC2")]
 fruits_asb_sp_relatw_b1 <- 
         alpha_fd_indices_fruits$details$asb_sp_relatw["basket_1", ]
         
 # Retrieve FEve plot:
 feve_plot <- feve.plot(ggplot_bg = ggplot_bg_fruits,
           asb_sp_coord2D = list(basket_1 = fruits_asb_sp_coord2D_b1),
           asb_sp_relatw = list(basket_1 = fruits_asb_sp_relatw_b1),
           asb_mst = fruits_asb_mst_b1,
           plot_sp = TRUE,
           shape_sp = 16,
           color_sp = "red",
           fill_sp = "red",
           color_mst = list(basket_1 = "blue"),
           width_mst = list(basket_1 = 1),
           linetype_mst = list(basket_1 = "solid"))
           
 feve_plot

---

Plot FIde index

Description

Plot FIde index given a pair of functional axes for one or several assemblages. It adds the centroid of species for each assemblage and segments showing centroid coordinates on functional axes on the background plot.

Usage

fide.plot(
  ggplot_bg,
  asb_sp_coord2D,
  asb_sp_relatw,
  asb_fide_coord2D,
  plot_sp = TRUE,
  shape_sp,
  color_sp,
  fill_sp,
  shape_fide,
  size_fide,
  color_fide,
  fill_fide,
  color_segment,
  width_segment,
  linetype_segment
)

Arguments

ggplot_bg	a ggplot object of the plot background retrieved through the background.plot function.
asb_sp_coord2D	a list of matrix (ncol = 2) with coordinates of species present in each assemblage for a given pair of functional axes.
asb_sp_relatw	a list of vector gathering species relative weight in each assemblage. It can be retrieved through the alpha.fd.multidim.
asb_fide_coord2D	a list (with names as in asb_sp_coord2D) of vectors with coordinates of the centroid of species for each assemblage for a given pair of axes.
plot_sp	a logical value indicating whether species of each assemblage should be plotted or not. Default: plot_sp = TRUE
shape_sp	a numeric value referring to the shape of the symbol used for species plotting if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRshape", asb2 = "secondRshape", ...).
color_sp	a R color name or an hexadecimal code referring to the color of species if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
fill_sp	a R color name or an hexadecimal code referring to the color of species symbol filling (if shape_sp > 20) if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
shape_fide	a numeric value referring to the shape of the symbol used for fide centroid plotting if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRshape", asb2 = "secondRshape", ...).
size_fide	a numeric value referring to the size of the symbol used for fide centroid plotting if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRsize", asb2 = "secondRsize", ...).
color_fide	a R color name or an hexadecimal code referring to the color of species centroid for agiven assemblage if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
fill_fide	a R color name or an hexadecimal code referring to the color to fill assemblage centroid symbol (if shape_sp > 20) if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
color_segment	a R color name or an hexadecimal code referring to the color of of the segment linking axes and centroid from the studied assemblage if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
width_segment	a numeric value referring to the width of the segment linking fide centroid and functional axes if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRsize", asb2 = "secondRsize", ...).
linetype_segment	a numeric value referring to the linetype of the segment linking fide centroid and functional axes if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRlinetype", asb2 = "secondRlinetype", ...).

Value

A ggplot object with FIde index, species and background.

Author(s)

Camille Magneville and Sebastien Villeger

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

# Set faxes limits:
# set range of axes if c(NA, NA):
 range_sp_coord_fruits  <- range(sp_faxes_coord_fruits)
 range_faxes_lim <- range_sp_coord_fruits + 
 c(-1, 1)*(range_sp_coord_fruits[2] - 
 range_sp_coord_fruits[1]) * 0.05
 
 # Retrieve the background plot:
 ggplot_bg_fruits <- mFD::background.plot(
                               range_faxes = range_faxes_lim, 
                               faxes_nm    = c("PC 1", "PC 2"), 
                               color_bg    = "grey90") 
                               
 # Retrieve the matrix of species coordinates for "basket_1" and PC1 and PC2
 sp_filter <- mFD::sp.filter(asb_nm          = "basket_1", 
                             sp_faxes_coord = sp_faxes_coord_fruits, 
                             asb_sp_w       = baskets_fruits_weights)
 fruits_asb_sp_coord_b1 <- sp_filter$`species coordinates`
 fruits_asb_sp_coord2D_b1 <- fruits_asb_sp_coord_b1[, c("PC1", "PC2")]
                               
 # Use alpha.fd.multidim() function to get inputs to plot FIde:
 alpha_fd_indices_fruits <- mFD::alpha.fd.multidim(
 sp_faxes_coord    = sp_faxes_coord_fruits[, c("PC1", "PC2", "PC3", "PC4")],
  asb_sp_w         = baskets_fruits_weights,
  ind_vect         = c("fide"),
  scaling          = TRUE,
  check_input      = TRUE,
  details_returned = TRUE)
  
 # Retrieve fide values through alpha.fd.multidim outputs:
 fruits_asb_fide_coord2D <- 
  alpha_fd_indices_fruits$functional_diversity_indices[c("fide_PC1", 
                                                         "fide_PC2")]
 fruits_asb_fide_coord2D_b1 <- fruits_asb_fide_coord2D[c("basket_1"), ]
 fruits_asb_sp_relatw_b1 <- 
         alpha_fd_indices_fruits$details$asb_sp_relatw["basket_1", ]
 
 # Retrieve FIde plot:
 fide_plot <- fide.plot(ggplot_bg = ggplot_bg_fruits,
           asb_sp_coord2D = list(basket_1 = fruits_asb_sp_coord2D_b1),
           asb_sp_relatw = list(basket_1 = fruits_asb_sp_relatw_b1),
           asb_fide_coord2D = list(basket_1 = fruits_asb_fide_coord2D_b1),
           plot_sp = TRUE,
           shape_sp = 16,
           color_sp = "red",
           fill_sp = "red",
           shape_fide = list(basket_1 = 18),
           size_fide = list(basket_1 = 5),
           color_fide = list(basket_1 = "blue"),
           fill_fide = list(basket_1 = "blue"),
           color_segment = list(basket_1 = "red"),
           width_segment = list(basket_1 = 1),
           linetype_segment = list(basket_1 = "dashed"))
           
 fide_plot

---

Plot FNND index

Description

This function plots FNND index for a given pair of functional axes and for one or several assemblages

Usage

fnnd.plot(
  ggplot_bg,
  asb_sp_coord2D,
  asb_sp_relatw,
  asb_nn_asb,
  plot_sp = TRUE,
  shape_sp,
  color_sp,
  fill_sp,
  color_segment,
  width_segment,
  linetype_segment
)

Arguments

ggplot_bg	a ggplot object of the plot background retrieved through the background.plot function.
asb_sp_coord2D	a list of matrix (ncol = 2) with coordinates of species present in each assemblage for a given pair of functional axes
asb_sp_relatw	a list of vector gathering species relative weight in each assemblage. It can be retrieved through the alpha.fd.multidim.
asb_nn_asb	a list gathering for each species of a studied assemblage its nearest neighbour(s) in the assemblage.
plot_sp	a logical value indicating whether species of each assemblage should be plotted or not. Default: plot_sp = TRUE
shape_sp	a numeric value referring to the shape used to plot species belonging to the studied assemblage.
color_sp	a R color name or an hexadecimal code referring to the color of species if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
fill_sp	a R color name or an hexadecimal code referring to the color of species symbol filling (if shape_sp > 20) if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
color_segment	a R color name or an hexadecimal code referring to the color of of the segment linking nearest neighbors in a given assemblage or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
width_segment	a numeric value referring to the size of the segment linking nearest neighbors in a given assemblage or a vector of numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRwidth", asb2 = "secondRwidth", ...).
linetype_segment	a character string referring to the linetype used to link nearest neighbors in the studied assemblages or a vector of character strings if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRlinetype", asb2 = "secondRlinetype", ...).

Value

A ggplot object with FNND index.

Author(s)

Camille Magneville and Sebastien Villeger

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

# Set faxes limits:
# set range of axes if c(NA, NA):
 range_sp_coord_fruits  <- range(sp_faxes_coord_fruits)
 range_faxes_lim <- range_sp_coord_fruits + 
 c(-1, 1)*(range_sp_coord_fruits[2] - 
 range_sp_coord_fruits[1]) * 0.05
 
 # Retrieve the background plot:
 ggplot_bg_fruits <- mFD::background.plot(
                               range_faxes = range_faxes_lim, 
                               faxes_nm    = c("PC 1", "PC 2"), 
                               color_bg    = "grey90") 
                               
 # Retrieve the matrix of species coordinates for "basket_1" and PC1 and PC2
 sp_filter <- mFD::sp.filter(asb_nm          = "basket_1", 
                             sp_faxes_coord = sp_faxes_coord_fruits, 
                             asb_sp_w       = baskets_fruits_weights)
 fruits_asb_sp_coord_b1 <- sp_filter$`species coordinates`
 fruits_asb_sp_coord2D_b1 <- fruits_asb_sp_coord_b1[, c("PC1", "PC2")]
                               
 # Use alpha.fd.multidim() function to get inputs to plot FIde:
 alpha_fd_indices_fruits <- mFD::alpha.fd.multidim(
  sp_faxes_coord   = sp_faxes_coord_fruits[, c("PC1", "PC2", "PC3", "PC4")],
  asb_sp_w         = baskets_fruits_weights,
  ind_vect         = c("fnnd"),
  scaling          = TRUE,
  check_input      = TRUE,
  details_returned = TRUE)
  
 # Retrieve nearest neighbor(s) names and relative weights ...
 # ... through alpha.fd.multidim outputs:
 fruits_asb_nn_asb_b1 <- 
         alpha_fd_indices_fruits$details$asb_nm_nn_asb["basket_1"]
 fruits_asb_sp_relatw_b1 <- 
         alpha_fd_indices_fruits$details$asb_sp_relatw["basket_1", ]

 # Retrieve FNND plot:
 fnnd_plot <- fnnd.plot(ggplot_bg = ggplot_bg_fruits,
           asb_sp_coord2D = list(basket_1 = fruits_asb_sp_coord2D_b1),
           asb_sp_relatw = list(basket_1 = fruits_asb_sp_relatw_b1),
           asb_nn_asb = fruits_asb_nn_asb_b1 ,
           plot_sp = TRUE,
           shape_sp = 16,
           color_sp = "red",
           fill_sp = "red",
           color_segment = list(basket_1 = "blue"),
           width_segment = list(basket_1 = 1),
           linetype_segment = list(basket_1 = "solid"))
           
 fnnd_plot

---

Plot FOri

Description

This function plots FOri index for a given pair of functional axes and for one or several assemblages. It adds the distance of species from the studied to their nearest neighbour(s) from the global pool.

Usage

fori.plot(
  ggplot_bg,
  asb_sp_coord2D,
  asb_sp_relatw,
  asb_nn_pool,
  pool_coord2D,
  plot_pool = TRUE,
  plot_sp = TRUE,
  shape_pool,
  size_pool,
  color_pool,
  fill_pool,
  shape_sp,
  color_sp,
  fill_sp,
  color_segment,
  width_segment,
  linetype_segment
)

Arguments

ggplot_bg	a ggplot object of the plot background retrieved through the background.plot function.
asb_sp_coord2D	a list of matrix (ncol = 2) with coordinates of species present in each assemblage for a given pair of functional axes.
asb_sp_relatw	a list of vector gathering species relative weight in each assemblage. It can be retrieved through the alpha.fd.multidim.
asb_nn_pool	a list gathering for each species of a studied assemblage its nearest neighbour(s) in the global pool.
pool_coord2D	a matrix (ncol = 2) with coordinates of species present in the global pool for a given pair of functional axes.
plot_pool	a logical value indicating whether species of each assemblage should be plotted or not. Default: plot_pool = TRUE.
plot_sp	a logical value indicating whether species of each assemblage should be plotted or not. Default: plot_sp = TRUE
shape_pool	a numeric value referring to the shape used to plot species pool.
size_pool	a numeric value referring to the size of species belonging to the global pool.
color_pool	a R color name or an hexadecimal code referring to the color of the pool. This color is also used for FRic convex hull color.
fill_pool	a R color name or an hexadecimal code referring to the colour to fill species symbol (if shape_sp > 20) and the assemblage convex hull.
shape_sp	a numeric value referring to the shape of the symbol used for species plotting if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRshape", asb2 = "secondRshape", ...).
color_sp	a R color name or an hexadecimal code referring to the color of species if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
fill_sp	a R color name or an hexadecimal code referring to the color of species symbol filling (if shape_sp > 20) if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
color_segment	color_segment a R color name or an hexadecimal code referring to the color of of the segment linking nearest neighbors in the global pool or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
width_segment	a numeric value referring to the size of the segment linking nearest neighbors in the global pool or a vector of numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRwidth", asb2 = "secondRwidth", ...).
linetype_segment	a character string referring to the linetype used to link nearest neighbors in the global pool or a vector of character strings if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRlinetype", asb2 = "secondRlinetype", ...).

Value

A ggplot object with FOri index.

Author(s)

Camille Magneville and Sebastien Villeger

Examples

## Not run: 
# 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

# Set faxes limits:
# set range of axes if c(NA, NA):
 range_sp_coord_fruits  <- range(sp_faxes_coord_fruits)
 range_faxes_lim <- range_sp_coord_fruits + 
 c(-1, 1)*(range_sp_coord_fruits[2] - 
 range_sp_coord_fruits[1]) * 0.05
 
 # Retrieve the background plot:
 ggplot_bg_fruits <- mFD::background.plot(
                               range_faxes = range_faxes_lim, 
                               faxes_nm    = c("PC 1", "PC 2"), 
                               color_bg    = "grey90") 
                               
 # Retrieve the matrix of species coordinates for "basket_1" and PC1 and PC2
 sp_filter <- mFD::sp.filter(asb_nm          = "basket_1", 
                             sp_faxes_coord = sp_faxes_coord_fruits, 
                             asb_sp_w       = baskets_fruits_weights)
 fruits_asb_sp_coord_b1 <- sp_filter$`species coordinates`
 fruits_asb_sp_coord2D_b1 <- fruits_asb_sp_coord_b1[, c("PC1", "PC2")]
                               
 # Use alpha.fd.multidim() function to get inputs to plot FIde:
 alpha_fd_indices_fruits <- mFD::alpha.fd.multidim(
  sp_faxes_coord   = sp_faxes_coord_fruits[, c("PC1", "PC2", "PC3", "PC4")],
  asb_sp_w         = baskets_fruits_weights,
  ind_vect         = c("fori"),
  scaling          = TRUE,
  check_input      = TRUE,
  details_returned = TRUE)
  
 # Retrieve nearest neighbor(s) names through alpha.fd.multidim outputs:
 fruits_asb_nn_pool_b1 <- 
         alpha_fd_indices_fruits$details$asb_nm_nn_pool["basket_1"]

 # Retrieve FNND plot:
 fori_plot <- fori.plot(ggplot_bg = ggplot_bg_fruits,
           asb_sp_coord2D = list(basket_1 = fruits_asb_sp_coord2D_b1),
           asb_sp_relatw = list(basket_1 = fruits_asb_sp_relatw_b1),
           asb_nn_pool = fruits_asb_nn_pool_b1,
           pool_coord2D = sp_faxes_coord_fruits[, c("PC1", "PC2")],
           plot_pool = TRUE,
           plot_sp = TRUE,
           shape_sp = 16,
           color_sp = "red",
           fill_sp = "red",
           shape_pool = 4,
           size_pool = 2,
           color_pool = "grey",
           fill_pool = "grey",
           color_segment = list(basket_1 = "red"),
           width_segment = list(basket_1 = 1),
           linetype_segment = list(basket_1 = "solid"))
           
 fori_plot

## End(Not run)

---

Plot FRic index

Description

This function plots FRic index for a given pair of functional axes and one or several assemblages. It adds convex hull(s), points and vertices of 1:N assemblages on the background plot

Usage

fric.plot(
  ggplot_bg,
  asb_sp_coord2D,
  asb_vertices_nD,
  plot_sp = TRUE,
  color_ch,
  fill_ch,
  alpha_ch,
  shape_sp,
  size_sp,
  color_sp,
  fill_sp,
  shape_vert,
  size_vert,
  color_vert,
  fill_vert
)

Arguments

ggplot_bg	a ggplot object of the plot background retrieved through the background.plot function.
asb_sp_coord2D	a list of matrix (ncol = 2) with coordinates of species present in each assemblage for a given pair of axes for a given pair of functional axes.
asb_vertices_nD	a list (with names as in asb_sp_coord2D) of vectors with names of species being vertices in n dimensions.
plot_sp	a logical value indicating whether species of each assemblage should be plotted or not. Default: plot_sp = TRUE.
color_ch	a R color name or an hexadecimal code referring to the color of the border of the convex hull filled by the pool of species if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
fill_ch	a R color name or an hexadecimal code referring to the color of convex hull filling if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
alpha_ch	a numeric value referring to the value of transparency of the convex hull filling (0 = high transparency, 1 = no transparency) if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRtransparency", asb2 = "secondRtransparency", ...).
shape_sp	a numeric value referring to the shape of the symbol used for species plotting if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRshape", asb2 = "secondRshape", ...).
size_sp	a numeric value referring to the size of the symbol used for species plotting if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRsize", asb2 = "secondRsize", ...).
color_sp	a R color name or an hexadecimal code referring to the color of species if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
fill_sp	a R color name or an hexadecimal code referring to the color of species symbol filling (if shape_sp > 20) if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
shape_vert	a numeric value referring to the shape of the symbol used for vertices plotting if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRshape", asb2 = "secondRshape", ...).
size_vert	a numeric value referring to the size of the symbol used for vertices plotting if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRsize", asb2 = "secondRsize", ...).
color_vert	a R color name or an hexadecimal code referring to the color of vertices if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...). If color_vert = NA, vertices are not plotted (for shapes only defined by color, ie shape inferior to 20. Otherwise fill must also be set to NA).
fill_vert	a R color name or an hexadecimal code referring to the color of vertices symbol filling (if shape_vert >20) if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...). If fill = NA and color = NA, vertices are not plotted (if shape_vert superior to 20

Value

A ggplot object plotting background of multidimensional graphs and FRic convex hulls.

Author(s)

Camille Magneville and Sebastien Villeger

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)
  
# 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
    
 # Retrieve species coordinates matrix for the assemblage "basket_1":
  sp_filter <- mFD::sp.filter(asb_nm          = c("basket_1"), 
                              sp_faxes_coord = sp_faxes_coord_fruits, 
                              asb_sp_w       = baskets_fruits_weights)
  sp_faxes_coord_fruits_b1 <- sp_filter$`species coordinates`
 
 # Reduce it to the two studid axes: PC1 and PC2:
 sp_faxes_coord_fruits_b1_2D <- sp_faxes_coord_fruits_b1[, c("PC1", "PC2")]

# Set faxes limits:
# set range of axes if c(NA, NA):
 range_sp_coord_fruits  <- range(sp_faxes_coord_fruits)
 range_faxes_lim <- range_sp_coord_fruits + c(-1, 1)*(range_sp_coord_fruits[2] - 
 range_sp_coord_fruits[1]) * 0.05
 
 # Retrieve the background plot:
 ggplot_bg_fruits <- mFD::background.plot(
                               range_faxes = range_faxes_lim, 
                               faxes_nm    = c("PC 1", "PC 2"), 
                               color_bg    = "grey90") 
                               
 # Retrieve vertices names:
 vert_nm_fruits <- vertices(sp_faxes_coord_fruits_b1_2D, 
  order_2D = TRUE, check_input = TRUE)
                               
 # Plot in white the convex hull of all fruits species:
 ggplot_fric <- mFD::fric.plot(
           ggplot_bg       = ggplot_bg_fruits,
           asb_sp_coord2D  = list(basket_1 = sp_faxes_coord_fruits_b1_2D),
           asb_vertices_nD = list(basket_1 = vert_nm_fruits),
           plot_sp         = TRUE,
           color_ch        = c("basket_1" = "black"), 
           fill_ch         = c("basket_1" = "white"), 
           alpha_ch        = c("basket_1" = 0.3),
           size_sp = c("basket_1" = 1),
           shape_sp = c("basket_1" = 16),
           color_sp = c("basket_1" = "red"),
           fill_sp = c("basket_1" = "red"),
           size_vert = c("basket_1" = 1),
           color_vert = c("basket_1" = "red"),
           fill_vert = c("basket_1" = "red"),
           shape_vert = c("basket_1" = 16))
 ggplot_fric

---

Dataset: Traits Values of Fruits Species

Description

This dataset represents the value of 6 traits for 15 fruits species. Important: Species names must be specified as the data frame row names (not in an additional column).

Usage

fruits_traits

Format

A data frame with 25 rows (species) and the following columns (traits):

Size

an ordered factor describing the size of fruits species

Plant

an unordered factor describing the type of plant

Climate

an ordered factor describing the climate regions

Seed

an ordered factor describing the type of seed

Sugar

a numeric describing the quantity of sugar

Use.raw

an integer (percentage) describing the proportion of a raw use (fuzzy trait) of the fruit

Use.pastry

an integer (percentage) describing the proportion of a pastry use (fuzzy trait) of the fruit

Use.jam

an integer (percentage) describing the proportion of a jam use (fuzzy trait) of the fruit

See Also

fruits_traits_cat, baskets_fruits_weights

Examples

## Not run: 
# Load Species x Traits Data Frame
data("fruits_traits", package = "mFD")
fruits_traits

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

# Summarize Species x Traits Data
mFD::sp.tr.summary(tr_cat = fruits_traits_cat, sp_tr = fruits_traits)

## End(Not run)

---

Dataset: Fruits Traits Informations

Description

This dataset summarizes information about the 6 traits used in the fruits_traits dataset.

Usage

fruits_traits_cat

Format

A data frame with 8 rows (traits) and the following three columns:

trait_name

a character giving the trait name

trait_type

a character giving the trait type (O for Ordinal trait, N for Nominal trait, Q for Quantitative trait, and F for Fuzzy-coded trait)

fuzzy_name

a character giving the name of fuzzy-coded traits (i.e. Use) to which 'sub-traits' (i.e. raw, pastry, and jam) belongs

Note

If your dataset does not contain fuzzy trait, the column fuzzy_name can be ignored but the first two columns are mandatory.

Traits in this dataset correspond to columns (traits) of the fruits_traits dataset.

See Also

fruits_traits, baskets_fruits_weights

Examples

## Not run: 
# Load Traits Information
data("fruits_traits_cat", package = "mFD")
fruits_traits_cat

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

# Summarize Species x Traits Data
mFD::sp.tr.summary(tr_cat = fruits_traits_cat, sp_tr = fruits_traits)

## End(Not run)

---

Plot FSpe

Description

This function plots FSpe index for a given pair of functional axes and for one or several assemblages. It adds the mean position of species from the global pool and the distance of each species from the studied assemblage(s) on the background plot

Usage

fspe.plot(
  ggplot_bg,
  asb_sp_coord2D,
  asb_sp_relatw,
  center_coord2D,
  pool_coord2D,
  plot_pool = TRUE,
  plot_sp = TRUE,
  shape_pool,
  size_pool,
  color_pool,
  fill_pool,
  shape_sp,
  color_sp,
  fill_sp,
  color_center,
  fill_center,
  shape_center,
  size_center,
  color_segment,
  width_segment,
  linetype_segment
)

Arguments

ggplot_bg	a ggplot object of the plot background retrieved through the background.plot function.
asb_sp_coord2D	a list of matrix (ncol = 2) with coordinates of species present in each assemblage for a given pair of functional axes.
asb_sp_relatw	a list of vector gathering species relative weight in each assemblage. It can be retrieved through the alpha.fd.multidim.
center_coord2D	a list containing the coordinates of the center of the global pool for two given functional axes
pool_coord2D	a list of matrix (ncol = 2) with coordinates of species present in the global pool for a given pair of functional axes.
plot_pool	a logical value indicating whether species of each assemblage should be plotted or not. Default: plot_pool = TRUE.
plot_sp	a logical value indicating whether species of each assemblage should be plotted or not. Default: plot_sp = TRUE
shape_pool	a numeric value referring to the shape used to plot species pool.
size_pool	a numeric value referring to the size of species belonging to the global pool.
color_pool	a R color name or an hexadecimal code referring to the color of the pool. This color is also used for FRic convex hull color. Default: color_pool = "#0072B2".
fill_pool	a R color name or an hexadecimal code referring to the colour to fill species symbol (if shape_sp > 20) and the assemblage convex hull.
shape_sp	a numeric value referring to the shape of the symbol used for species plotting if one assemblage to plot or a vector numeric values if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRshape", asb2 = "secondRshape", ...).
color_sp	a R color name or an hexadecimal code referring to the color of species if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
fill_sp	a R color name or an hexadecimal code referring to the color of species symbol filling (if shape_sp > 20) if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
color_center	a R color name or an hexadecimal code referring to the color of the center of the global pool.
fill_center	a R color name or an hexadecimal code referring to the colour to fill the center of the global pool (if shape_sp > 20).
shape_center	a numeric value referring to the shape used to plot the center of the global pool.
size_center	a numeric value referring to the size of the center of the global pool.
color_segment	a R color name or an hexadecimal code referring to the color of the segments linking each species of a given assemblage to the center of functional space if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRcolorname", asb2 = "secondRcolorname", ...).
width_segment	a numeric value referring to the width of the segments linking each species of a given assemblage to the center of functional space if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRwidth", asb2 = "secondRwidth", ...).
linetype_segment	a character string referring to the linetype of the segment linking each species of a given assemblage to the center of functional space if one assemblage to plot or a vector of R color names or hexadecimal codes if several assemblages to plot. If more than one assemblage to plot, the vector should be formatted as: c(asb1 = "firstRlinetype", asb2 = "secondRlinetype", ...).

Value

A ggplot object with FSpe index on the background plot.

Author(s)

Camille Magneville and Sebastien Villeger

Examples

## Not run: 
# 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

# Set faxes limits:
# set range of axes if c(NA, NA):
 range_sp_coord_fruits  <- range(sp_faxes_coord_fruits)
 range_faxes_lim <- range_sp_coord_fruits + 
 c(-1, 1)*(range_sp_coord_fruits[2] - 
 range_sp_coord_fruits[1]) * 0.05
 
 # Retrieve the background plot:
 ggplot_bg_fruits <- mFD::background.plot(
                               range_faxes = range_faxes_lim, 
                               faxes_nm    = c("PC 1", "PC 2"), 
                               color_bg    = "grey90") 
                               
 # Retrieve the matrix of species coordinates for "basket_1" and PC1 and PC2
 sp_filter <- mFD::sp.filter(asb_nm          = "basket_1", 
                             sp_faxes_coord = sp_faxes_coord_fruits, 
                             asb_sp_w       = baskets_fruits_weights)
 fruits_asb_sp_coord_b1 <- sp_filter$`species coordinates`
 fruits_asb_sp_coord2D_b1 <- fruits_asb_sp_coord_b1[, c("PC1", "PC2")]
                               
 # Use alpha.fd.multidim() function to get inputs to plot FIde:
 alpha_fd_indices_fruits <- mFD::alpha.fd.multidim(
  sp_faxes_coord   = sp_faxes_coord_fruits[, c("PC1", "PC2", "PC3", "PC4")],
  asb_sp_w         = baskets_fruits_weights,
  ind_vect         = c("fspe"),
  scaling          = TRUE,
  check_input      = TRUE,
  details_returned = TRUE)
  
 # Retrieve nearest neighbor(s) names through alpha.fd.multidim outputs:
 fruits_center_coord2D <- 
         alpha_fd_indices_fruits$details$pool_O_coord[c("PC1", "PC2")]

 
 # Retrieve FNND plot:
 fspe_plot <- fspe.plot(ggplot_bg = ggplot_bg_fruits,
           asb_sp_coord2D = list(basket_1 = fruits_asb_sp_coord2D_b1),
           asb_sp_relatw = list(basket_1 = fruits_asb_sp_relatw_b1),
           center_coord2D = fruits_center_coord2D,
           pool_coord2D = sp_faxes_coord_fruits[, c("PC1", "PC2")],
           plot_pool = TRUE,
           plot_sp = TRUE,
           shape_sp = 16,
           color_sp = "red",
           fill_sp = "red",
           shape_pool = 4,
           size_pool = 2,
           color_pool = "grey",
           fill_pool = "grey",
           color_center = "blue", 
           fill_center = "blue",
           shape_center = 18, 
           size_center = 3,
           color_segment = list(basket_1 = "red"),
           width_segment = list(basket_1 = 1),
           linetype_segment = list(basket_1 = "solid"))
           
 fspe_plot

## End(Not run)

---

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

---

Plot species position in a functional space

Description

This function illustrates the position of species along pairs of axes of a functional space

Usage

funct.space.plot(
  sp_faxes_coord,
  faxes = NULL,
  name_file = NULL,
  faxes_nm = NULL,
  range_faxes = c(NA, NA),
  color_bg = "grey95",
  color_pool = "darkturquoise",
  fill_pool = "white",
  shape_pool = 21,
  size_pool = 1,
  plot_ch = TRUE,
  color_ch = "darkblue",
  fill_ch = "white",
  alpha_ch = 1,
  plot_vertices = TRUE,
  color_vert = "darkturquoise",
  fill_vert = "darkturquoise",
  shape_vert = 22,
  size_vert = 1,
  plot_sp_nm = NULL,
  nm_size = 3,
  nm_color = "black",
  nm_fontface = "plain",
  check_input = TRUE
)

Arguments

sp_faxes_coord	a matrix of species coordinates in a multidimensional functional space. Species coordinates have been retrieved thanks to tr.cont.fspace or quality.fspaces.
faxes	a vector with names of axes to plot (as columns names in sp_faxes_coord). You can only plot from 2 to 4 axes for graphical reasons. Default: faxes = NULL (the four first axes will be plotted).
name_file	a character string with name of file to save the figure (without extension). Default: name_file = NULL which means plot is displayed.
faxes_nm	a vector with axes labels for figure. Default: as faxes).
range_faxes	a vector with minimum and maximum values of axes used for all plots to have a fair representation of position of species. Default: range_faxes = c(NA, NA) (the range is computed according to the range of values among all axes). If at least one of the value provided is within the range of coordinates, then convex hull could not be plotted so plot_ch should be FALSE.
color_bg	a R color name or an hexadecimal code used to fill plot background. Default: color_bg = "grey95".
color_pool	a R color name or an hexadecimal code referring to the color of symbol for species. Default: color_pool = 'darkgreen'.
fill_pool	a R color name or an hexadecimal code referring to the color to fill species symbol (if shape_pool >20). Default: fill_pool = 'white'.
shape_pool	a numeric value referring to the shape of symbol used for species. Default: shape_pool = 21 (filled circle).
size_pool	a numeric value referring to the size of symbol for species. Default: size_pool = 1.
plot_ch	a logical value indicating whether the convex hull shaping the pool of species should be illustrated. If plot_ch = TRUE, convex hull of all species in the multidimensional space described in sp_faxes_coord is computed and its projection in 2D spaces are drawn as polygons. Default: plot_ch = TRUE.
color_ch	a R color name or an hexadecimal code referring to the border of the convex hull filled by the pool of species. Default: color_ch = "darkblue".
fill_ch	a R color name or an hexadecimal code referring to the filling of the convex hull filled by the pool of species. Default: fill_ch = "white".
alpha_ch	a numeric value for transparency of the filling of the convex hull (0 = high transparency, 1 = no transparency). Default: alpha_ch = 1.
plot_vertices	a logical value defining whether vertices of the convex hull shaping the pool of species should be illustrated. If plot_vertices = TRUE, vertices of convex hull computed in the multidimensional space from sp_faxes_coord and are plotted with aesthetics listed below '..._vert' (species not being vertices are plotted with aesthetics described above for '.._sp'. Default: plot_vertices = TRUE.
color_vert	a character value referring to the color of symbol for vertices if plot_vertices = TRUE. Default: color_vert = 'darkturquoise'.
fill_vert	a character value referring to the color for filling symbol for vertices (if shape_vert >20). Default: fill_vert = 'darkturquoise'.
shape_vert	a numeric value referring to the symbol used to show vertices position if plot_vertices = TRUE. Default: shape_vert = 23 (filled diamond).
size_vert	a numeric value referring to the size of symbol for vertices Default: size_vert = 1.
plot_sp_nm	a vector containing species names that are to be printed near their position. Default: plot_nm_sp = NULL (no name plotted).
nm_size	a numeric value for size of species label. Default is 3 (in points).
nm_color	a R color name or an hexadecimal code referring to the color of species label. Default: nm_color = 'black'.
nm_fontface	a character string for font of species labels (e.g. "italic", "bold"). Default: nm_fontface = 'plain'.
check_input	a logical value indicating whether key features the inputs are checked (e.g. class and/or mode of objects, names of rows and/or columns, missing values). If an error is detected, a detailed message is returned. Default: check_input = TRUE.

Value

If name_file is NULL, a list containing ggplot2 objects is returned: plots of functional space along all pairs of axes (named according to axes names, e.g. "PC1_PC2"), figure 'caption', and the full figure 'patchwork' built using the library patchwork. If name_file is not NULL a 300dpi png file is saved in the working directory. Ranges of axes are the same for all panels and if required projection of the convex hull computed in the multidimensional space provided as input sp_faxes_coord is illustrated with a polygon. Species being vertices of this convex hull are shown with aesthetics provided as inputs ..._vert. Labels for species listed in plot_sp_nm are added with if required arrows using ggrepel. Summary about species and dimensionality are printed on top-right corner of the figure.

Author(s)

Camille Magneville and Sebastien Villeger

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)

# 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

# Plot functional spaces:
mFD::funct.space.plot(
 sp_faxes_coord    = sp_faxes_coord_fruits[, c("PC1", "PC2", "PC3", "PC4")],
  faxes             = NULL,
  name_file         = NULL,
  faxes_nm          = NULL,
  range_faxes       = c(NA, NA),
  color_bg          = "grey95",
  color_pool          = "darkturquoise",
  fill_pool           = "white",
  shape_pool          = 21,
  size_pool           = 1,
  plot_ch           = TRUE,
  color_ch          = "darkblue",
  fill_ch           = "white",
  alpha_ch          = 1,
  plot_vertices     = TRUE,
  color_vert        = "darkturquoise",
  fill_vert         = "darkturquoise",
  shape_vert        = 22,
  size_vert         = 1,
 plot_sp_nm         = NULL,
 nm_size            = 3,
 nm_color           = "black",
 nm_fontface        = "plain",
 check_input        = TRUE)

---

Compute FUSE (Functionally Unique, Specialized and Endangered)

Description

This index takes into account species functional uniqueness (also called Functional Originality), species specialisation and species IUCN status.

Usage

fuse(sp_dist, sp_faxes_coord, nb_NN = 5, GE, standGE = FALSE)

Arguments

sp_dist	a dist object provided by funct.dist, daisy or dist.ktab.
sp_faxes_coord	a data frame with the coordinates of the species on a multidimensional space based on a selected number of axes derived from a Principal Coordinate Analysis (PCoA). The species are in rows and the PCOA axes are in column.
nb_NN	a numerical value giving the number of nearest neighbor to consider. Default: nb_NN = 5.
GE	a numerical vector giving the IUCN status rank (DD = NA, LC = 0, NT = 1, VU = 2, EN = 3, CR = 4) or the IUCN extinction probability associated with each status. See Mooers et al. (2008) for further information. For example, DD = NA, LC = 0, NT = 0.1, VU = 0.4, EN = 0.666, and CR = 0.999).
standGE	a logical value to standardize the GE values.

Value

A data frame with species in rows and the following metrics in columns:

• FUSE: functionally unique, specialized and endangered (see Pimiento et al. (2020);

• FUn_std: functional uniqueness standardized between 0 and 1 (see Mouillot et al. (2013);

• FSp_std: functional specialization standardized between 0 and 1 (see Mouillot et al. (2013);

Author(s)

Fabien Leprieur and Camille Albouy

References

Mouillot et al. (2013) Rare species support vulnerable functions in high-diversity ecosystems. PLoS Biology, 11, e1001569.
Pimiento et al. (2020) Functional diversity of marine megafauna in the Anthropocene. Science Advances, 6, eaay7650.
Violle et al. (2007) Let the concept of trait be functional! Oikos, 116, 882-892.

Examples

# Load species traits data:
sp_tr <- read.csv(system.file('extdata', 'data_traits_MMA_ursus.csv', 
  package = 'mFD'), dec = ',', sep = ';', header = TRUE, row.names = 1,
  na.strings='NA')

# Trait compilation and ordination:
dimorphism      <- ordered(sp_tr$dimorphism)
breeding_site   <- ordered(sp_tr$breeding_site)
social_behavior <- ordered(sp_tr$social_behavior)
weight_max      <- log(sp_tr$adult_weight_max)
social_group    <- log(sp_tr$social_group_mean)
 
# Trait Matrix construction:
sp_tr_end <- data.frame(
  main_diet = sp_tr$main_diet, 
  foraging_water_depth = sp_tr$foraging_water_depth,
  foraging_location = sp_tr$foraging_location, 
  fasting_strategy = sp_tr$fasting_strategy,
  female_sexual_maturity = sp_tr$female_sexual_maturity, 
  weaning = sp_tr$weaning,
  gestation = sp_tr$gestation, inter_litter = sp_tr$inter_litter,
  breeding_site = sp_tr$breeding_site, 
  social_group = sp_tr$social_group_mean,
  social_behavior = sp_tr$social_behavior, 
  weight_max = sp_tr$adult_weight_max,
  dimorphism = sp_tr$dimorphism)
  
rownames(sp_tr_end) <- rownames(sp_tr)
 
# Function weigthing vector:
v <- c(0.25, 0.25, 0.25, 0.25, 0.20, 0.20, 0.20, 0.20, 0.20, 0.5, 0.5, 0.5, 
  0.5)
   
# Gower distance calculation:
sp_tr_end$main_diet <- as.factor(sp_tr_end$main_diet)
sp_tr_end$foraging_water_depth <- as.factor(sp_tr_end$foraging_water_depth)
sp_tr_end$foraging_location <- as.factor(sp_tr_end$foraging_location)
sp_tr_end$breeding_site <- as.factor(sp_tr_end$breeding_site)
sp_tr_end$social_behavior <- as.factor(sp_tr_end$social_behavior)

sp_dist_tr <- cluster::daisy(sp_tr_end, metric = c('gower'), 
  type = list(symm = c(4)), weights = v)
  
# Principal coordinate analyses
Pcoa <- ade4::dudi.pco(ade4::quasieuclid(sp_dist_tr), scann = FALSE, 
                       nf = 40)

sp_faxes_coord <- Pcoa$li[1:40]
 
# FUSE calculation:
 FUSE_res <- mFD::fuse(
    sp_dist        = sp_dist_tr, 
    sp_faxes_coord = as.matrix(sp_faxes_coord), 
    nb_NN          = 5,  
    GE             = sp_tr$IUCN_num,
    standGE        = TRUE)
 FUSE_res
    
 FUSE_res2 <- mFD::fuse(
    sp_dist        = sp_dist_tr, 
    sp_faxes_coord = as.matrix(sp_faxes_coord), 
    nb_NN          = 5,
    GE             = sp_tr$IUCN_50,
    standGE        = TRUE)
 FUSE_res2
    
 FUSE_res3 <- mFD::fuse(
    sp_dist        = sp_dist_tr, 
    sp_faxes_coord = as.matrix(sp_faxes_coord), 
    nb_NN          = 5, 
    GE             = sp_tr$IUCN_100,
    standGE        = TRUE)
 FUSE_res3

---

Compute the Minimum Spanning Tree (MST) linking species of a given assemblage

Description

This function computes the MST linking species of a given assemblage and is used to compute FEve index.

Usage

mst.computation(sp_faxes_coord_k)

Arguments

sp_faxes_coord_k

a matrix relating species coordinates for species present in a given assemblage.

Value

A dist object summarizing the MST for all species of a given assemblage mst_asb_k.

Author(s)

Camille Magneville and Sebastien Villeger

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

# Compute the distance of "pear" to its nearest neighbor(s):
 mst_fruits <- mst.computation(sp_faxes_coord_fruits)
 mst_fruits

---

Plot individual plots along a pair of functional axes into a unique graph

Description

This function gathers panels into a unique patchwork graph with caption.

Usage

panels.to.patchwork(panels, plot_caption)

Arguments

panels	a list of ggplot objects illustrating an index on two given functional axes. There must be either one, three or six ggplot objects given the number of studied functional axes.
plot_caption	a ggplot object illustrating the caption of the final patchwork plot.

Value

A unique ggplot object gathering functional panels and caption.

Author(s)

Camille Magneville and Sebastien Villeger

Examples

## Retrieve FRic plot:
# 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
    
 # Retrieve species coordinates matrix for the assemblage "basket_1":
  sp_filter <- mFD::sp.filter(asb_nm          = c("basket_1"), 
                              sp_faxes_coord = sp_faxes_coord_fruits, 
                              asb_sp_w       = baskets_fruits_weights)
  sp_faxes_coord_fruits_b1 <- sp_filter$`species coordinates`
 
 # Reduce it to the two studed axes: PC1 and PC2:
 sp_faxes_coord_fruits_b1_2D <- sp_faxes_coord_fruits_b1[, c("PC1", "PC2")]

# Set faxes limits:
# set range of axes if c(NA, NA):
 range_sp_coord_fruits  <- range(sp_faxes_coord_fruits)
 range_faxes_lim <- range_sp_coord_fruits + c(-1, 1)*(range_sp_coord_fruits[2] - 
 range_sp_coord_fruits[1]) * 0.05
 
 # Retrieve the background plot:
 ggplot_bg_fruits <- mFD::background.plot(
                               range_faxes = range_faxes_lim, 
                               faxes_nm    = c("PC 1", "PC 2"), 
                               color_bg    = "grey90") 
                               
 # Retrieve vertices names:
 vert_nm_fruits <- vertices(sp_faxes_coord_fruits_b1_2D, 
  order_2D = TRUE, check_input = TRUE)
                               
 # Plot in white the convex hull of all fruits species:
 ggplot_fric <- mFD::fric.plot(
           ggplot_bg       = ggplot_bg_fruits,
           asb_sp_coord2D  = list(basket_1 = sp_faxes_coord_fruits_b1_2D),
           asb_vertices_nD = list(basket_1 = vert_nm_fruits),
           plot_sp         = TRUE,
           color_ch        = c("basket_1" = "black"), 
           fill_ch         = c("basket_1" = "white"), 
           alpha_ch        = c("basket_1" = 0.3),
           size_sp = c("basket_1" = 1),
           shape_sp = c("basket_1" = 16),
           color_sp = c("basket_1" = "red"),
           fill_sp = c("basket_1" = "red"),
           size_vert = c("basket_1" = 1),
           color_vert = c("basket_1" = "red"),
           fill_vert = c("basket_1" = "red"),
           shape_vert = c("basket_1" = 16))
 ggplot_fric
 
## Create a caption summing up FRic values 
# retrieve values to plot:
top_fric <- c("Functional richness", "basket_1", "")

asb_fd_ind <- alpha_fd_indices_fruits <- mFD::alpha.fd.multidim(
sp_faxes_coord   = sp_faxes_coord_fruits[ , c("PC1", "PC2", "PC3", "PC4")],
asb_sp_w         = baskets_fruits_weights,
ind_vect         = c("fric"),
scaling          = TRUE,
check_input      = TRUE,
details_returned = TRUE)

values_fric <- c(round(asb_fd_ind$functional_diversity_indices["basket_1", 
"fric"], 3), "")

# customize position of texts in the plot:
spread_faxes <- (range_sp_coord_fruits[2] - range_sp_coord_fruits[1])
hh <- c(1, 2.5, 4, 5.5)
vv <- 0.3

# plot window:
x <- NULL
y <- NULL
plot_caption <- ggplot2::ggplot(data.frame(x = range_sp_coord_fruits, 
                                          y = range_sp_coord_fruits),
                               ggplot2::aes(x = x, y = y)) +
 ggplot2::scale_x_continuous(limits = range_sp_coord_fruits, 
 expand = c(0, 0)) +
 ggplot2::scale_y_continuous(limits = range_sp_coord_fruits, 
 expand = c(0, 0)) +
 ggplot2::theme_void() + ggplot2::theme(legend.position = "none") +
 ggplot2::geom_rect(xmin = range_sp_coord_fruits[1], 
                    xmax = range_sp_coord_fruits[2],
                    ymin = range_sp_coord_fruits[1], 
                    ymax = range_sp_coord_fruits[2],
                    fill = "white", colour ="black")

# plot names of index and of assemblages:
h   <- NULL
v   <- NULL
top <- NULL
x <- NULL
y <- NULL
plot_caption <- plot_caption +
 ggplot2::geom_text(data = data.frame(
   h = range_sp_coord_fruits[1] + spread_faxes * 0.15 * hh[c(1,3:4)],
   v = range_sp_coord_fruits[2] - spread_faxes * rep(0.2, 3),
   top = top_fric),
   ggplot2::aes(x = h, y = v, label = top),
   size = 3, hjust = 0.5, fontface = "bold")

# plot FRic values:
values_lab <- NULL
data_caption <- data.frame(
  h = range_sp_coord_fruits[1] + spread_faxes * 0.15 * hh[2:4],
  v = range_sp_coord_fruits[2] - spread_faxes*rep(vv, 3),
  values_lab = c("FRic", values_fric))
plot_caption <- plot_caption +
  ggplot2::geom_text(data = data_caption,
                    ggplot2::aes(x = h, y = v, label = values_lab),
                    size = 3, hjust = 0.5, fontface = "plain")

## Create patchwork:
patchwork_fric <- mFD::panels.to.patchwork(list(ggplot_fric), plot_caption)
patchwork_fric

---