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.

`distinctiveness(pres_matrix, dist_matrix, relative = FALSE)`

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

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 = \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.

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(pres_matrix = mat, dist_matrix = dist_mat)
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.1460428 NA 0.2039929 NA 0.1788624
#> AR54 NA NA NA 0.1786867 NA
#> AR60 NA NA NA NA NA
# 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)
```