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

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

Camille Magneville and Sebastien Villeger

## Examples

if (FALSE) {
data("fruits_traits", package = "mFD")

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_faxes_coord = sp_faxes_coord_fruits,
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,
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,