R/distinctiveness_range.R
distinctiveness_range.RdComputes functional distinctiveness from a site-species matrix (containing presence-absence or relative abundances) of species with provided functional distance matrix considering only species within a given range in the functional space. The sites-species matrix should have sites in rows and species in columns, similar to vegan package defaults.
distinctiveness_range(pres_matrix, dist_matrix, given_range, relative = FALSE)a site-species matrix (presence-absence or relative abundances), with sites in rows and species in columns
a species functional distance matrix
a numeric indicating the dissimilarity range at which the the influence of other species is not considered anymore
a logical indicating if distinctiveness should be scaled relatively to the community (scaled by max functional distance among the species of the targeted community)
a similar matrix from provided pres_matrix with Distinctiveness
values in lieu of presences or relative abundances, species absent from
communities will have an NA value (see Note section)
The Functional Distinctiveness of a species is the average functional distance from a species to all the other in the given community. It is computed as such: $$ D_i(T) = 1 ~~ if ~~ T < min(d_{ij}), \\ D_i(T) = \left( \frac{ \sum\limits_{j = 1 ~, j \neq i ~, d_{ij} \leq T}^S d_{ij} \times Ab_j }{ \sum\limits_{ j = 1 ~, j \neq i ~, d_{ij} \leq T}^S Ab_j } \right) \times \left(1 - \frac{ \sum\limits_{ j = 1 ~, j \neq i ~, d_{ij} \leq T}^S Ab_j }{ N } \right) ~~ if ~~ T \geq min(d_{ij}), $$ with \(D_i\) the functional distinctiveness of species \(i\), \(N\) the total number of species in the community and \(d_{ij}\) the functional distance between species \(i\) and species \(j\). \(T\) is the chosen maximal range considered. When presence-absence are used \(Ab_j = 1/N\) and the term \( \left(1 - \frac{ \sum\limits_{ j = 1 ~, j \neq i ~, d_{ij} \leq T}^S Ab_j }{ N } \right)\) is replaced by 1. IMPORTANT NOTE: in order to get functional rarity indices between 0 and 1, the distance metric has to be scaled between 0 and 1.
Absent species should be coded by 0 or NA in input matrices.
When a species is alone in its community the functional distinctiveness
cannot be computed (denominator = 0 in formula), and its value is assigned
as NaN.
For speed and memory efficiency sparse matrices can be used as input of
the function using as(pres_matrix, "dgCMatrix") from the
Matrix package.
(see vignette("sparse_matrices", package = "funrar"))
data("aravo", package = "ade4")
# Site-species matrix
mat = as.matrix(aravo$spe)
# Compute relative abundances
mat = make_relative(mat)
# Example of trait table
tra = aravo$traits[, c("Height", "SLA", "N_mass")]
# Distance matrix
dist_mat = compute_dist_matrix(tra)
#> Only numeric traits provided, consider using euclidean distance.
di = distinctiveness_range(pres_matrix = mat, dist_matrix = dist_mat, 0.2)
di[1:5, 1:5]
#> Agro.rupe Alop.alpi Anth.nipp Heli.sede Aven.vers
#> AR07 NA NA NA NA NA
#> AR71 NA NA NA NA NA
#> AR26 0.03154571 NA 0.06630241 NA 0.05027471
#> AR54 NA NA NA 0.04490106 NA
#> AR60 NA NA NA NA NA