distinctiveness {funrar}

Functional Distinctiveness on site-species matrix

Description

Computes functional distinctiveness from a site-species matrix (containing presence-absence or relative abundances) of species with provided functional distance matrix. The sites-species matrix should have sites in rows and species in columns, similar to vegan package defaults.

Usage

distinctiveness(pres_matrix, dist_matrix, relative = FALSE)

Arguments

pres_matrix

a site-species matrix (presence-absence or relative abundances), with sites in rows and species in columns

dist_matrix

a species functional distance matrix

relative

a logical indicating if distinctiveness should be scaled relatively to the community (scaled by max functional distance among the species of the targeted community)

Details

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 = \frac{\sum_{j = 0, i \neq j}^N d_{ij}}{N-1},

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. IMPORTANT NOTE: in order to get functional rarity indices between 0 and 1, the distance metric has to be scaled between 0 and 1.

Value

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)

Note

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

Examples

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)

di = distinctiveness(pres_matrix = mat, dist_matrix = dist_mat)
di[1:5, 1:5]

# Compute distinctiveness for all species in the regional pool
# i.e., with all the species in all the communities
# Here considering each species present evenly in the regional pool
reg_pool = matrix(1, ncol = ncol(mat))
colnames(reg_pool) = colnames(mat)
row.names(reg_pool) = c("Regional_pool")

reg_di = distinctiveness(reg_pool, dist_mat)