Nothing
Introduction to funrar through an example"
In funrar: Functional Rarity Indices Computation
Introduction
The idea of Functional Rarity is to measure two components of the rarity of a species (or an individual). In community ecology, researchers are generally interested in the rarity of a species as measured in terms of abundances. A species with a low abundance will be considered 'rare'. From a functional ecology perspective, this omits important information about the "role" that a given species plays in the ecosystem, its particular niche. A framework is being developed of various indices to characterize how functioning can be rare locally or regionally
In their article, Violle et al. (2017) introduced 4 indices to compute functional rarity indices. funrar package enables ecologists to compute these on any dataset.
Framework
The following figure show the 4 aspects covered by the metrics. Rarity is thus considered at local and regional scales and also from abundance and functional point of views. The name of the package functions are written underneath metrics' names.
Dataset example
To illustrate the package, we are using a dataset describing the distribution of 82 species of Alpine plants in 75 sites. This dataset was collected by Choler et al.(2005).
Species traits and environmental variables are also available.
data("aravo", package = "ade4")
str(aravo)
Functional rarity indices
Inputs of functions
For each metric, the package includes two functions, depending on the input type.
Ecologist usually have to deal with site-species matrix, containing sites names as rows, species in columns and either abundances or presence/absence data (see example datasets in vegan or ade4 packages for example). Thus, this matrix is needed as an input for each simple function.
# Site-species matrix stored in aravo$spe
mat = as.matrix(aravo$spe)
mat[1:5, 1:5]
metricname() functions can be used to compute indices directly on site-species matrices.
Users can also use a stacked (or tidy) data.frame, containing columns for sites, species and abundances. The package contains for each metric another function called metricname_stack() function that can take these stacked data.frames as inputs.
funrar package includes two functions to go from one format to the other: matrix_to_stack() and stack_to_matrix()
library(funrar)
dat = matrix_to_stack(mat, "value", "site", "species")
head(dat)
# The reverse function is provided and gives the same original matrix
identical(
as.numeric(stack_to_matrix(dat, "site", "species", "value")), as.numeric(mat)
)
# Removal of empty rows
dat = dat[which(dat$value > 0), ]
The package is also able to deal with large matrices with many zeroes by using sparse matrices. For more details, see sparse_matrices vignette.
Indices
Distance matrix computation
The indices rely on the computation of a distance matrix. It represents the functional distance between two species given a particular set of traits. From a species traits matrix you can easily compute a distance matrix using function compute_dist_matrix().
In order to compute distance matrix, species names must be specified as rownames in the traits table. Further, species names must match between the traits table and distance matrix. Species names must be characters and not factors.
The function relies on the daisy() function from package cluster and the default metric is Gower's distance to take into account ordinal, categorical and binary traits:
tra = aravo$traits[, c("Height", "SLA", "N_mass")]
head(tra)
dist_mat = compute_dist_matrix(tra)
dist_mat[1:5, 1:5]
Using the metric argument in compute_dist_matrix() you can specify other distance metrics (euclidean for Euclidean distances and manhattan for Manhattan distances) for functional distances. You can also compute your own distance matrix with other methods as long as it is a matrix and both row names and column names are species names.
Functional Distinctiveness computation
Formula
The distinctiveness measures how a species is locally functionally rare, in comparison with the other species of community. Each species (or individual) in each community will get a distinctiveness value. Distinctiveness values range from 0 to 1. A value of 0 indicates that the focal species is not locally functionally distant from the other and conversely.
From given functional distances, it is computed as such:
$$
D_i = \frac{\sum_{\substack{j = 1, \
i \neq j
}}^{N} d_{ij}}{N-1},
$$
with $D_i$ distinctiveness of species $i$, $d_{ij}$ the functional distance between species $i$ and species $j$, $N$ the number of species present in considered community.
When weighted by abundances the formula becomes:
$$
D_i = \frac{\sum_{\substack{j = 1, \
i \neq j
}}^{N} d_{ij}\times A_j}{\sum_{\substack{j = 1, \
i \neq j
}}^{N} A_j},
$$
with the same terms as above, and $A_j$ the relative abundance of species $j$ in percent, in the community.
Computation with site-species matrix
Using funrar functional distinctiveness can be computed using function distinctiveness():
# Compute distinctiveness for each species on each site
di = distinctiveness(pres_matrix = mat, # The site x species matrix
dist_matrix = dist_mat) # Functional Distance matrix
di[1:5, 1:5]
The syntax for distinctiveness() is first the matrix and then the functional distance matrix. The function returns a site-species matrix filled with Di values, i.e. the species functional distinctiveness in each species per site combination.
Computation with stacked data.frame
Using funrar distinctiveness values can be computed using function distinctiveness_stack():
# Species should be character
dat$species = as.character(dat$species)
# Compute distinctiveness for each species on each site
di_df = distinctiveness_stack(
com_df = dat, # The site x species table
sp_col = "species", # Name of the species column
com = "site", # Name of the community column
abund = NULL, # Relative abundances column (facultative)
dist_matrix = dist_mat # Functional Distance matrix
)
head(di_df)
The syntax for distinctiveness_stack() is first the table, then the name of the species column, then the name of the community column, then the name of the relative abundance column and finally the distance matrix. The function add a Di column giving the species distinctiveness in each species per site combination.
For abundance weighted distinctiveness you need to have a column containing relative abundances in your data frame as such:
di_df = distinctiveness_stack(dat, "species", "site", "value", dist_mat)
head(di_df)
Scarcity
Formula
The scarcity measures how locally abundant a species is, in comparison to the other species of community. Each species (or individual) in each community will get a scarcity value. Scarcity values range from 0 to 1. A 0 value indicates that the focal species is locally abundant and conversely.
$$
S_i = \exp(-NA_i\log2),
$$
with $S_i$ the scarcity of species $i$, $N$ the number of species in the local community, $A_i$ the relative abundance (in percent) of species $i$ in the community.
Computation
With funrar it can be computed with scarcity() function with a syntax analog to distinctiveness()
si = scarcity(pres_matrix = mat)
si[1:5, 1:5]
Scarcity requires relative abundances to be computed. We thus have to convert
our dataset with abundances to relative abundances. To do that we first compute
total abundances per site.
# Compute relative abundances
site_abundances = aggregate(value ~ site, data = dat, FUN = sum)
colnames(site_abundances)[2] = "total_abundance"
dat = merge(dat, site_abundances, by = "site")
dat$rel_abund = dat[["value"]] / dat[["total_abundance"]]
head(dat)
Then we can compute Scarcity using relative abundances:
si_df = scarcity_stack(dat, "species", "site", "rel_abund")
head(si_df)
Uniqueness
Formula
Uniqueness measures how functionally rare a species is at the regional scale. Each species (or individual) in the species pool will get a uniqueness value. Uniqueness values range from 0 to 1. A 0 value indicates that the focal species shares the exact same traits as other species in the pool and conversely.
$$
U_i = \text{min}(d_{ij}), \forall j \in [1, N_R], j \neq i,
$$
with $U_i$ the uniqueness of species $i$, $d_{ij}$ the functional distance between species $i$ and species $j$, $N_R$ the number of species in the regional pool.
Computation
uniqueness() follows a similar syntax, but beware that given community table and distance matrix should represent the regional species pool. And the syntax is also similar:
ui = uniqueness(mat, dist_mat)
head(ui)
ui_df = uniqueness_stack(dat, "species", dist_mat)
head(ui_df)
dim(ui_df[!duplicated(ui_df$species), ])
Geographical Restrictedness
Formula
Restrictedness measures how regionally rare a species is. The following function represents a species' occupancy for a set of communities. Each species (or individual) in the species pool will have a restrictedness value. Restrictedness values range from 0 to 1. A 0 value indicates that the focal species is present in all the sites.
$$
R_i = 1 - N_i/N_tot
$$
with $R_i$ the restrictedness of species $i$, $N_i$ the number of sites where species $i$ is found and $N_tot$ the total number of sites.
Computation
ri = restrictedness(mat)
head(ri)
# Species should be character
dat$site = as.character(dat$site)
ri_df = restrictedness_stack(dat, "species", "site")
head(ri_df)
funrar
This function computes all of the four metrics introduced above.
all_ind = funrar(mat, dist_mat, rel_abund = TRUE)
str(all_ind)
identical(all_ind$Ui, ui)
identical(all_ind$Di, di)
identical(all_ind$Ri, ri)
identical(all_ind$Si, si)
Plots
In this section, some ideas to plot your results are presented. For example the density of the various indices or a matrix visualization of the values of distinctiveness per species.
library(ggplot2)
# Heatmap with distinctiveness values
ggplot(di_df, aes(species, site)) +
geom_tile(aes(fill = Di), colour = "white") +
scale_fill_gradient(low = "white", high = "steelblue")
# Density of distinctiveness values
quant = quantile(di_df$Di, probs = seq(0, 1, 0.10))
labels_quant = paste(names(quant)[-length(quant)], names(quant)[-1], sep = "-")
di_density = data.frame(density(di_df$Di)[c("x", "y")])
di_density = subset(di_density, x >= quant[[1]] & x <= quant[[length(quant)]])
di_density$quant = cut(di_density$x, breaks = quant)
quant = quantile(di_df$Di, probs = seq(0, 1, 0.10))
labels_quant = paste(names(quant)[-length(quant)], names(quant)[-1], sep = "-")
di_dens = ggplot(data = di_density, aes(x = x, y = y)) +
geom_area(aes(fill = quant)) +
scale_fill_brewer(palette = "RdYlBu", labels = labels_quant,
name = "Quantile") +
geom_line(size = 1) +
xlab("Distinctiveness values") +
ylab("Frequency") +
ggtitle("Density of distinctiveness values") +
theme_classic()
di_dens
# Density of scarcity values
quant = quantile(si_df$Si, probs = seq(0, 1, 0.10))
labels_quant = paste(names(quant)[-length(quant)], names(quant)[-1], sep = "-")
si_density = data.frame(density(si_df$Si)[c("x", "y")])
si_density = subset(si_density, x >= quant[[1]] & x <= quant[[length(quant)]])
si_density$quant = cut(si_density$x, breaks = quant)
quant = quantile(si_df$Si, probs = seq(0, 1, 0.10))
labels_quant = paste(names(quant)[-length(quant)], names(quant)[-1], sep = "-")
si_dens = ggplot(data = si_density, aes(x = x, y = y)) +
geom_area(aes(fill = quant)) +
scale_fill_brewer(palette = "RdYlBu", labels = labels_quant,
name = "Quantile") +
geom_line(size = 1) +
xlab("Scarcity values") +
ylab("Frequency") +
ggtitle("Density of scarcity values") +
theme_classic()
si_dens
# Regional rarity: restrictedness versus uniqueness
colnames(ri_df)[colnames(ri_df) == "sp"] = "species"
ri_ui <- merge(ri_df, ui_df, by = "species")
ggplot(ri_ui, aes(Ri, Ui)) +
geom_point() +
theme_classic()
References
Choler, P. (2005) Consistent shifts in Alpine plant traits along a mesotopographical gradient. Arctic, Antarctic, and Alpine Research, 37,444-453.
Violle C., Thuiller W., Mouquet N., Munoz F., Kraft NJB, Cadotte MW, Livingstone SW, Mouillot D., Functional Rarity: The Ecology of Outliers, Trends in Ecology & Evolution, Volume 32, Issue 5, May 2017, Pages 356-367, ISSN 0169-5347, https://doi.org/10.1016/j.tree.2017.02.002.
Try the funrar package in your browser
Any scripts or data that you put into this service are public.
funrar documentation built on Sept. 23, 2022, 5:10 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Introduction
The idea of Functional Rarity is to measure two components of the rarity of a species (or an individual). In community ecology, researchers are generally interested in the rarity of a species as measured in terms of abundances. A species with a low abundance will be considered 'rare'. From a functional ecology perspective, this omits important information about the "role" that a given species plays in the ecosystem, its particular niche. A framework is being developed of various indices to characterize how functioning can be rare locally or regionally
In their article, Violle et al. (2017) introduced 4 indices to compute functional rarity indices. funrar package enables ecologists to compute these on any dataset.
Framework
The following figure show the 4 aspects covered by the metrics. Rarity is thus considered at local and regional scales and also from abundance and functional point of views. The name of the package functions are written underneath metrics' names.
Dataset example
To illustrate the package, we are using a dataset describing the distribution of 82 species of Alpine plants in 75 sites. This dataset was collected by Choler et al.(2005).
Species traits and environmental variables are also available.
data("aravo", package = "ade4") str(aravo)
Functional rarity indices
Inputs of functions
For each metric, the package includes two functions, depending on the input type.
Ecologist usually have to deal with site-species matrix, containing sites names as rows, species in columns and either abundances or presence/absence data (see example datasets in vegan or ade4 packages for example). Thus, this matrix is needed as an input for each simple function.
# Site-species matrix stored in aravo$spe mat = as.matrix(aravo$spe) mat[1:5, 1:5]
metricname() functions can be used to compute indices directly on site-species matrices.
Users can also use a stacked (or tidy) data.frame, containing columns for sites, species and abundances. The package contains for each metric another function called metricname_stack() function that can take these stacked data.frames as inputs.
funrar package includes two functions to go from one format to the other: matrix_to_stack() and stack_to_matrix()
library(funrar) dat = matrix_to_stack(mat, "value", "site", "species") head(dat) # The reverse function is provided and gives the same original matrix identical( as.numeric(stack_to_matrix(dat, "site", "species", "value")), as.numeric(mat) ) # Removal of empty rows dat = dat[which(dat$value > 0), ]
The package is also able to deal with large matrices with many zeroes by using sparse matrices. For more details, see sparse_matrices vignette.
Indices
Distance matrix computation
The indices rely on the computation of a distance matrix. It represents the functional distance between two species given a particular set of traits. From a species traits matrix you can easily compute a distance matrix using function compute_dist_matrix().
In order to compute distance matrix, species names must be specified as rownames in the traits table. Further, species names must match between the traits table and distance matrix. Species names must be characters and not factors.
The function relies on the daisy() function from package cluster and the default metric is Gower's distance to take into account ordinal, categorical and binary traits:
tra = aravo$traits[, c("Height", "SLA", "N_mass")] head(tra) dist_mat = compute_dist_matrix(tra) dist_mat[1:5, 1:5]
Using the metric argument in compute_dist_matrix() you can specify other distance metrics (euclidean for Euclidean distances and manhattan for Manhattan distances) for functional distances. You can also compute your own distance matrix with other methods as long as it is a matrix and both row names and column names are species names.
Functional Distinctiveness computation
Formula
The distinctiveness measures how a species is locally functionally rare, in comparison with the other species of community. Each species (or individual) in each community will get a distinctiveness value. Distinctiveness values range from 0 to 1. A value of 0 indicates that the focal species is not locally functionally distant from the other and conversely.
From given functional distances, it is computed as such: $$ D_i = \frac{\sum_{\substack{j = 1, \ i \neq j }}^{N} d_{ij}}{N-1}, $$ with $D_i$ distinctiveness of species $i$, $d_{ij}$ the functional distance between species $i$ and species $j$, $N$ the number of species present in considered community.
When weighted by abundances the formula becomes: $$ D_i = \frac{\sum_{\substack{j = 1, \ i \neq j }}^{N} d_{ij}\times A_j}{\sum_{\substack{j = 1, \ i \neq j }}^{N} A_j}, $$ with the same terms as above, and $A_j$ the relative abundance of species $j$ in percent, in the community.
Computation with site-species matrix
Using funrar functional distinctiveness can be computed using function distinctiveness():
# Compute distinctiveness for each species on each site di = distinctiveness(pres_matrix = mat, # The site x species matrix dist_matrix = dist_mat) # Functional Distance matrix di[1:5, 1:5]
The syntax for distinctiveness() is first the matrix and then the functional distance matrix. The function returns a site-species matrix filled with Di values, i.e. the species functional distinctiveness in each species per site combination.
Computation with stacked data.frame
Using funrar distinctiveness values can be computed using function distinctiveness_stack():
# Species should be character dat$species = as.character(dat$species) # Compute distinctiveness for each species on each site di_df = distinctiveness_stack( com_df = dat, # The site x species table sp_col = "species", # Name of the species column com = "site", # Name of the community column abund = NULL, # Relative abundances column (facultative) dist_matrix = dist_mat # Functional Distance matrix ) head(di_df)
The syntax for distinctiveness_stack() is first the table, then the name of the species column, then the name of the community column, then the name of the relative abundance column and finally the distance matrix. The function add a Di column giving the species distinctiveness in each species per site combination.
For abundance weighted distinctiveness you need to have a column containing relative abundances in your data frame as such:
di_df = distinctiveness_stack(dat, "species", "site", "value", dist_mat) head(di_df)
Scarcity
Formula
The scarcity measures how locally abundant a species is, in comparison to the other species of community. Each species (or individual) in each community will get a scarcity value. Scarcity values range from 0 to 1. A 0 value indicates that the focal species is locally abundant and conversely.
$$ S_i = \exp(-NA_i\log2), $$
with $S_i$ the scarcity of species $i$, $N$ the number of species in the local community, $A_i$ the relative abundance (in percent) of species $i$ in the community.
Computation
With funrar it can be computed with scarcity() function with a syntax analog to distinctiveness()
si = scarcity(pres_matrix = mat) si[1:5, 1:5]
Scarcity requires relative abundances to be computed. We thus have to convert our dataset with abundances to relative abundances. To do that we first compute total abundances per site.
# Compute relative abundances site_abundances = aggregate(value ~ site, data = dat, FUN = sum) colnames(site_abundances)[2] = "total_abundance" dat = merge(dat, site_abundances, by = "site") dat$rel_abund = dat[["value"]] / dat[["total_abundance"]] head(dat)
Then we can compute Scarcity using relative abundances:
si_df = scarcity_stack(dat, "species", "site", "rel_abund") head(si_df)
Uniqueness
Formula
Uniqueness measures how functionally rare a species is at the regional scale. Each species (or individual) in the species pool will get a uniqueness value. Uniqueness values range from 0 to 1. A 0 value indicates that the focal species shares the exact same traits as other species in the pool and conversely.
$$ U_i = \text{min}(d_{ij}), \forall j \in [1, N_R], j \neq i, $$
with $U_i$ the uniqueness of species $i$, $d_{ij}$ the functional distance between species $i$ and species $j$, $N_R$ the number of species in the regional pool.
Computation
uniqueness() follows a similar syntax, but beware that given community table and distance matrix should represent the regional species pool. And the syntax is also similar:
ui = uniqueness(mat, dist_mat) head(ui)
ui_df = uniqueness_stack(dat, "species", dist_mat) head(ui_df) dim(ui_df[!duplicated(ui_df$species), ])
Geographical Restrictedness
Formula
Restrictedness measures how regionally rare a species is. The following function represents a species' occupancy for a set of communities. Each species (or individual) in the species pool will have a restrictedness value. Restrictedness values range from 0 to 1. A 0 value indicates that the focal species is present in all the sites.
$$ R_i = 1 - N_i/N_tot $$
with $R_i$ the restrictedness of species $i$, $N_i$ the number of sites where species $i$ is found and $N_tot$ the total number of sites.
Computation
ri = restrictedness(mat) head(ri)
# Species should be character dat$site = as.character(dat$site) ri_df = restrictedness_stack(dat, "species", "site") head(ri_df)
funrar
This function computes all of the four metrics introduced above.
all_ind = funrar(mat, dist_mat, rel_abund = TRUE) str(all_ind) identical(all_ind$Ui, ui) identical(all_ind$Di, di) identical(all_ind$Ri, ri) identical(all_ind$Si, si)
Plots
In this section, some ideas to plot your results are presented. For example the density of the various indices or a matrix visualization of the values of distinctiveness per species.
library(ggplot2) # Heatmap with distinctiveness values ggplot(di_df, aes(species, site)) + geom_tile(aes(fill = Di), colour = "white") + scale_fill_gradient(low = "white", high = "steelblue") # Density of distinctiveness values quant = quantile(di_df$Di, probs = seq(0, 1, 0.10)) labels_quant = paste(names(quant)[-length(quant)], names(quant)[-1], sep = "-") di_density = data.frame(density(di_df$Di)[c("x", "y")]) di_density = subset(di_density, x >= quant[[1]] & x <= quant[[length(quant)]]) di_density$quant = cut(di_density$x, breaks = quant) quant = quantile(di_df$Di, probs = seq(0, 1, 0.10)) labels_quant = paste(names(quant)[-length(quant)], names(quant)[-1], sep = "-") di_dens = ggplot(data = di_density, aes(x = x, y = y)) + geom_area(aes(fill = quant)) + scale_fill_brewer(palette = "RdYlBu", labels = labels_quant, name = "Quantile") + geom_line(size = 1) + xlab("Distinctiveness values") + ylab("Frequency") + ggtitle("Density of distinctiveness values") + theme_classic() di_dens # Density of scarcity values quant = quantile(si_df$Si, probs = seq(0, 1, 0.10)) labels_quant = paste(names(quant)[-length(quant)], names(quant)[-1], sep = "-") si_density = data.frame(density(si_df$Si)[c("x", "y")]) si_density = subset(si_density, x >= quant[[1]] & x <= quant[[length(quant)]]) si_density$quant = cut(si_density$x, breaks = quant) quant = quantile(si_df$Si, probs = seq(0, 1, 0.10)) labels_quant = paste(names(quant)[-length(quant)], names(quant)[-1], sep = "-") si_dens = ggplot(data = si_density, aes(x = x, y = y)) + geom_area(aes(fill = quant)) + scale_fill_brewer(palette = "RdYlBu", labels = labels_quant, name = "Quantile") + geom_line(size = 1) + xlab("Scarcity values") + ylab("Frequency") + ggtitle("Density of scarcity values") + theme_classic() si_dens # Regional rarity: restrictedness versus uniqueness colnames(ri_df)[colnames(ri_df) == "sp"] = "species" ri_ui <- merge(ri_df, ui_df, by = "species") ggplot(ri_ui, aes(Ri, Ui)) + geom_point() + theme_classic()
References
Choler, P. (2005) Consistent shifts in Alpine plant traits along a mesotopographical gradient. Arctic, Antarctic, and Alpine Research, 37,444-453.
Violle C., Thuiller W., Mouquet N., Munoz F., Kraft NJB, Cadotte MW, Livingstone SW, Mouillot D., Functional Rarity: The Ecology of Outliers, Trends in Ecology & Evolution, Volume 32, Issue 5, May 2017, Pages 356-367, ISSN 0169-5347, https://doi.org/10.1016/j.tree.2017.02.002.
Try the funrar package in your browser
Any scripts or data that you put into this service are public.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.