[Vegan-commits] r1624 - in pkg/vegan: inst man

[noreply at r-forge.r-project.org]

Author: jarioksa
Date: 2011-06-04 12:49:19 +0200 (Sat, 04 Jun 2011)
New Revision: 1624

Modified:
   pkg/vegan/inst/ChangeLog
   pkg/vegan/man/vegdist.Rd
Log:
tell that the Raup-Crick index in vegdist may not work in the way it should

Modified: pkg/vegan/inst/ChangeLog
===================================================================
--- pkg/vegan/inst/ChangeLog	2011-06-04 10:19:14 UTC (rev 1623)
+++ pkg/vegan/inst/ChangeLog	2011-06-04 10:49:19 UTC (rev 1624)
@@ -4,6 +4,17 @@
 
 Version 1.18-32 (opened May 30, 2011)
 
+	* vegdist docs: Brian Inouye informed us that we are not
+	calculating the Raup-Crick index like originally suggested: we use
+	equal probabilities for all species, but the species probabilities
+	should vary with their frequencies. Doing this would break
+	vegdist.c design, and require Fisher's non-central hypergeometric
+	distribution, and that is not available in base R. However, it
+	seems that a simulation version could be implemented in
+	oecosimu(). Now we document the problems in vegdist.Rd, but do not
+	correct the behaviour. The key paper is available over
+	http://www.esajournals.org/doi/full/10.1890/ES10-00117.1
+
 	* rda & capscale: similar changes as in cca in r1517 (version
 	1.18-24). CA component is always returned, even with zero rank,
 	and CCA and pCCA components are NULL only if they were not

Modified: pkg/vegan/man/vegdist.Rd
===================================================================
--- pkg/vegan/man/vegdist.Rd	2011-06-04 10:19:14 UTC (rev 1623)
+++ pkg/vegan/man/vegdist.Rd	2011-06-04 10:49:19 UTC (rev 1624)
@@ -149,22 +149,24 @@
   are divided by \eqn{\log(2)}{log(2)} so that the results will be in
   the conventional range \eqn{0 \dots 1}.
 
-  Raup--Crick dissimilarity (\code{method = "raup"}) is a probabilistic
-  index based on presence/absence data.  It is defined as \eqn{1 - prob(j)},
-  or based on the probability of observing at least \eqn{j} 
-  species in shared in compared communities.  Legendre & Legendre (1998)
-  suggest
-  using simulations to assess the probability, but the current function
-  uses analytic result from hypergeometric distribution
-  (\code{\link{phyper}}) instead.  This probability (and the index) is
-  dependent on the number of species missing in both sites, and adding
-  all-zero species to the data or removing missing species from the data
-  will influence the index.  The probability (and the index) may be
-  almost zero or almost one for a wide range of parameter values.  The
-  index is nonmetric: two
-  communities with no shared species may have a dissimilarity slightly
-  below one, and two identical communities may have dissimilarity
-  slightly above zero.
+  Raup--Crick dissimilarity (\code{method = "raup"}) is a
+  probabilistic index based on presence/absence data.  It is defined
+  as \eqn{1 - prob(j)}, or based on the probability of observing at
+  least \eqn{j} species in shared in compared communities.  Legendre &
+  Legendre (1998) suggest using simulations to assess the probability,
+  but the current function uses analytic result from hypergeometric
+  distribution (\code{\link{phyper}}) instead.  This probability (and
+  the index) is dependent on the number of species missing in both
+  sites, and adding all-zero species to the data or removing missing
+  species from the data will influence the index.  The probability
+  (and the index) may be almost zero or almost one for a wide range of
+  parameter values.  The index is nonmetric: two communities with no
+  shared species may have a dissimilarity slightly below one, and two
+  identical communities may have dissimilarity slightly above
+  zero. Please note that this index does not implement the Raup--Crick
+  dissimilarity as discussed by Chase et al. (2011): the current index
+  uses equal probabilities for all species, but the probabilities
+  should be inequal and based on species frequencies.
   
   Chao index tries to take into account the number of unseen species
   pairs, similarly as in \code{method = "chao"} in
@@ -226,6 +228,11 @@
   Chao, A., Chazdon, R. L., Colwell, R. K. and Shen, T. (2005). A new
   statistical approach for assessing similarity of species composition
   with incidence and abundance data. \emph{Ecology Letters} 8, 148--159.
+
+  Chase, J.M., Kraft, N.J.B., Smith, K.G., Vellend, M. and Inouye,
+  B.D. (2011). Using null models to disentangle variation in community
+  dissimilarity from variation in \eqn{\alpha}{alpha}-diversity.
+  \emph{Ecosphere} 2:art24 [doi:10.1890/ES10-00117.1]
    
   Faith, D. P, Minchin, P. R. and Belbin, L. (1987).
   Compositional dissimilarity as a robust measure of ecological