## Functional Rarefaction for Species Abundance Data

### Description

The function `Rare_Rao` performs distance-based rarefaction curves using species abundance data. It finds the expected functional diversity (if functional distances between species are used) as a function of the sampling effort. Two approaches are available: an analytical solution, a resampling approach.

### Usage

```rare_Rao(comm, dis, sim = TRUE, resampling = 999, formula = c("QE", "EDI"))
```

### Arguments

 `comm` a data frame or a matrix with samples as rows, species as columns, and abundance or frequency as entries. If presences/absences (1/0) are given, the relative abundance of a given species in a community of S species will be considered equal to 1/S. `dis` an object of class `dist` containing pairwise distances among species. The distance matrix should be squared Euclidean or simply Euclidean (see definition and details in Appendix S1 of Ricotta et al. (2012)). Alternatively, if `dis` is `NULL`, the Gini-Simpson index is used. `sim` a logical; if `TRUE`, the resampling approach is used; if `FALSE`, the analytical solution is given. `resampling` a numeric; number of times data are resampled to calculate the mean functional rarefaction curve (used if `sim=TRUE`). `formula` either `"QE"` (default) or `"EDI"`. See details.

### Details

If `formula = "QE"`, the definition of the quadratic entropy is:

QE(p_i,D)=sum_k,l p_k|i p_k|j d_kl

where p_i=(p_1|i, ..., p_k|i, ..., p_S|i) is the vector of relative species abundance within sample i; S is the number of species; D=(d_kl) is the matrix of (phylogenetic or functional) dissimilarities among species, and d_kl is the (phylogenetic or functional) dissimilarity between species k and l.

If `formula = "EDI"`, the definition of the quadratic entropy is:

EDI(p_i,D)=sum_k,l p_k|i p_k|j (d_kl^2)/2

EDI stands for the Euclidean Diversity Index of Champely and Chessel (2002) (equation 3 in Pavoine et al. 2004).

In both cases, if `dis = NULL`, the quadratic entropy is equal to Gini-Simpson entropy:

H_GS(p_i)=1 - sum_k (p_k|i)^2

### Value

If `sim = TRUE`, the function returns a data frame containing the Expected Rao Quadratic Entropy (column 'ExpRao'), the limits of the 95% Confidence Interval (columns 'LeftIC' and 'RightIC') for each subsample dimension (M) out of the total set of samples (N). If `sim = FALSE`, the function returns a data frame containing the analytical solution for the Expected Rao Quadratic Entropy (column 'ExpRao') for each subsample dimension (M) out of the total set of samples (N).

### Author(s)

Giovanni Bacaro and Sandrine Pavoine sandrine.pavoine@mnhn.fr

### References

Ricotta, C., Pavoine, S., Bacaro, G., Acosta, A. (2012) Functional rarefaction for species abundance data. Methods in Ecology and Evolution, 3, 519–525.

Champely, S. and Chessel, D. (2002) Measuring biological diversity using Euclideanmetrics. Environmental and Ecological Statistics, 9, 167–177.

Pavoine, S., Dufour, A.B., Chessel, D. (2004) From dissimilarities among species to dissimilarities among communities: a double principal coordinate analysis. Journal of Theoretical Biology, 228, 523–537.

`QE`

### Examples

```## Not run:

# Trait-based distances between bird species:
distances<-dist.ktab(ktab.list.df(list(aviurba\$traits)), type = "N")
# The distances should be squared Euclidean;
# note that Euclidean distances can be used
# as they also are squared Euclidean.

# Species abundances in sites
abundances<- aviurba\$fau

# Rarefaction of functional diversity
rare_Rao(abundances, distances, sim = TRUE, resampling = 100)
rare_Rao(abundances, distances, sim = FALSE)

}

## End(Not run)
```