distinctAb {adiv}

Abundance-based measures of species' rarity, functional or phylogenetic distinctiveness and functional or phylogenetic effective originality

Description

The function calculates parametric indices of species' rarity and functional or phylogenetic distinctiveness and effective originality according to Pavoine and Ricotta (2021).

Usage

distinctAb(comm, disORtree, method = c("Q", "KY", "KstarI"), palpha = 2, 
    option = c("asymmetric", "symmetric"), tol = 1e-10)

Arguments

comm

a data frame or a matrix typically with communities as rows, species as columns and abundance as entry. Species should be labelled as in object disORtree.

disORtree

an object inheriting the class dist, giving the FP-dissimilarities between species, or inheriting the class phylo (see package ape), phylo4 (see package phylobase), or hclust, where species are tips.

method

a string either "Q" for the quadratic entropy, "KY" for index ^{\alpha}K (if disORtree is of class dist) or ^{\alpha}Y if disORtree is of class phylo, phylo4 or hclust; or "KstarI" for index ^{\alpha}K* (if disORtree is of class dist) or ^{\alpha}I if disORtree is of class phylo, phylo4 or hclust. If several values are given, only the first one is considered.

palpha

a numeric, nonnegative value for parameter \alpha. palpha is ignored if method = "Q".

option

a string either "asymmetric", or"symmetric" The parameter option is only used if disORtree is of class phylo, phylo4 or hclust If option="symmetric", the distance between two tips on a tree is defined as half the sum of branch length on the smallest path that connects the two species; while if option="asymmetric" the distance between a tip i and a tip j on a tree is defined as the sum of branch lengths between tip i and its most recent ancestor with tip j. If the tree is ultrametric, the two options are equivalent.

tol

numeric tolerance threshold: values between -tol and tol are considered equal to zero.

Value

If palpha <= 1, then, the function returns a list of four objects of class data.frame (with communities as rows and species as columns): TotContr provides for each species in each community the effective originality multiplied by the relative abundance; EffOriPres provides for each species present in each community the effective originality; NA for absent species; DistinctPres provides for each species present in each community the distinctiveness; NA for absent species; Rarity provides for each species in each community the rarity (maximum rarity for absent species).

Else, the function returns a list with the three objects of class data.frame presented above and two additional objects also of class data.frame: EffOriAll provides for each species its effective originality compared with the composition of each community; even absent species have a value considering they have zero abundance so maximum rarity and considering their functional dissimilarity or phylogenetic dissimilarity with all species present in each community; DistinctAll provides for each species its effective originality compared with the composition of each community; even absent species have a value considering they have zero abundance so maximum rarity and considering their functional dissimilarity or phylogenetic dissimilarity with all species present in each community.

Author(s)

Sandrine Pavoine [e-mail]

References

Pavoine, S., Ricotta, C. (2021) On the relationships between rarity, uniqueness, distinctiveness, originality and functional/phylogenetic diversity. BiorXiv. doi:10.1101/2021.08.09.455640

See Also

distinctDis, distinctTopo, distinctTree, distinctUltra

Examples

## Not run: 
if(require(ape) && require(adephylo) && require(phylobase)){
data(batcomm)
phy <- read.tree(text=batcomm$tre2)
disAb <- distinctAb(batcomm$ab2, phy, method="Q") 
U.4d <- phylo4d(phy, t(disAb[[2]]))
dotp4d(U.4d, center = FALSE, scale = FALSE, data.xlim = range(t(disAb[[2]]), na.rm=TRUE), 
    tree.ratio = 0.20, dot.cex=2)
title("Effective originality associated with quadratic entropy (diversity)")
}

## End(Not run)