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

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

Author: psolymos
Date: 2009-05-04 22:03:58 +0200 (Mon, 04 May 2009)
New Revision: 818

Modified:
   pkg/vegan/R/tsallis.R
   pkg/vegan/inst/ChangeLog
   pkg/vegan/man/tsallis.Rd
Log:
tsallis got new arg: hill

Modified: pkg/vegan/R/tsallis.R
===================================================================
--- pkg/vegan/R/tsallis.R	2009-05-04 19:34:07 UTC (rev 817)
+++ pkg/vegan/R/tsallis.R	2009-05-04 20:03:58 UTC (rev 818)
@@ -1,6 +1,8 @@
 tsallis <-
-function (x, scales = seq(0, 2, 0.2), norm=FALSE)
+function (x, scales = seq(0, 2, 0.2), norm=FALSE, hill=FALSE)
 {
+    if (norm && hill)
+        stop("'norm = TRUE' and 'hill = TRUE' should not be used at the same time")
     x <- as.matrix(x)
     n <- nrow(x)
     p <- ncol(x)
@@ -26,6 +28,9 @@
             if (scales[a] == 1) result[, a] <- result[, a] / log(ST)
             else result[, a] <- result[, a] / ((ST^(1-scales[a]) - 1) / (1 - scales[a]))
         }
+        if (hill) {
+            result[, a] <- (1 - (scales[a] - 1) * result[, a])^(1/(1-scales[a]))
+        }
     }
     result <- as.data.frame(result)
     if (any(dim(result) == 1)) 

Modified: pkg/vegan/inst/ChangeLog
===================================================================
--- pkg/vegan/inst/ChangeLog	2009-05-04 19:34:07 UTC (rev 817)
+++ pkg/vegan/inst/ChangeLog	2009-05-04 20:03:58 UTC (rev 818)
@@ -4,6 +4,8 @@
 
 Version 1.16-18 (opened April 21, 2009)
 
+	* tsallis: got new argument 'hill' similar that of renyi.
+
 	* twostagechao: function that calculates multiple-community
 	similarity based on Chao et al. 2008 (Biometrics 64, 1178-86).
 	Some debugging is needed since it cannot reproduce the numbers

Modified: pkg/vegan/man/tsallis.Rd
===================================================================
--- pkg/vegan/man/tsallis.Rd	2009-05-04 19:34:07 UTC (rev 817)
+++ pkg/vegan/man/tsallis.Rd	2009-05-04 20:03:58 UTC (rev 818)
@@ -8,7 +8,7 @@
 Function \code{tsallis} find Tsallis diversities with any scale or the corresponding evenness measures. Function \code{tsallisaccum} finds these statistics with accumulating sites.
 }
 \usage{
-tsallis(x, scales = seq(0, 2, 0.2), norm = FALSE)
+tsallis(x, scales = seq(0, 2, 0.2), norm = FALSE, hill = FALSE)
 tsallisaccum(x, scales = seq(0, 2, 0.2), permutations = 100, raw = FALSE, ...)
 \method{persp}{tsallisaccum}(x, theta = 220, phi = 15, col = heat.colors(100), zlim, ...)
 }
@@ -17,6 +17,7 @@
   \item{x}{Community data matrix or plotting object. }
   \item{scales}{Scales of Tsallis diversity.}
   \item{norm}{Logical, if \code{TRUE} diversity values are normalized by their maximum (diversity value at equiprobability conditions).}
+  \item{hill}{Calculate Hill numbers.}
   \item{permutations}{Number of random permutations in accumulating sites.}
   \item{raw}{If \code{FALSE} then return summary statistics of permutations, and if TRUE then returns the individual permutations.}
   \item{theta, phi}{angles defining the viewing direction. \code{theta} gives the azimuthal direction and \code{phi} the colatitude.}
@@ -32,29 +33,36 @@
 
 where \eqn{q} is a scale parameter, \eqn{S} the number of species in the sample (Tsallis 1988, Tothmeresz 1995). This diversity is concave for all \eqn{q>0}, but non-additive (Keylock 2005). For \eqn{q=0} it gives the number of species minus one, as \eqn{q} tends to 1 this gives Shannon diversity, for \eqn{q=2} this gives the Simpson index (see function \code{\link{diversity}}).
 
-When \code{norm = TRUE}, \code{tsallis} gives values normalized by the maximum:
+If \code{norm = TRUE}, \code{tsallis} gives values normalized by the maximum:
 
 \deqn{H_q(max) = \frac{S^{1-q}-1}{1-q}}{H.q(max) = (S^(1-q)-1)/(1-q)}
 
 where \eqn{S} is the number of species. As \eqn{q} tends to 1, maximum is defined as \eqn{ln(S)}.
 
+If \code{hill = TRUE}, \code{tsallis} gives Hill numbers (numbers equivalents, see Jost 2007):
+
+\deqn{D_q = (1-(q-1) H)^(1/(1-q))}{D.q = (1-(q-1)*H)^(1/(1-q))}
+
 Details on plotting methods and accumulating values can be found on the help pages of the functions \code{\link{renyi}} and \code{\link{renyiaccum}}.
 }
 \value{
 Function \code{tsallis} returns a data frame of selected indices. Function \code{tsallisaccum} with argument \code{raw = FALSE} returns a three-dimensional array, where the first dimension are the accumulated sites, second dimension are the diveristy scales, and third dimension are the summary statistics \code{mean}, \code{stdev}, \code{min}, \code{max}, \code{Qnt 0.025} and \code{Qnt 0.975}. With argument \code{raw = TRUE} the statistics on the third dimension are replaced with individual permutation results.
 }
 \references{
-Tsallis, C. (1988). Possible generalization of Boltzmann-Gibbs statistics. 
+Tsallis, C. (1988) Possible generalization of Boltzmann-Gibbs statistics. 
   \emph{J. Stat. Phis.} 52, 479--487.
 
-Tothmeresz, B. (1995). Comparison of different methods for diversity
-  ordering. \emph{Journal of Vegetation Science} 6, 283--290.
+Tothmeresz, B. (1995) Comparison of different methods for diversity
+  ordering. \emph{Journal of Vegetation Science} \bold{6}, 283--290.
 
-Patil, GP and Taillie, C. (1982). Diversity as a concep and its measurement.
-  \emph{J. Am. Stat. Ass.} 77, 548--567.
+Patil, G. P. and Taillie, C. (1982) Diversity as a concep and its measurement.
+  \emph{J. Am. Stat. Ass.} \bold{77}, 548--567.
 
-Keylock, CJ (2005). Simpson diversity and the Shannon-Wiener index as special cases of a generalized entropy.
-  \emph{Oikos} 109, 203--207.
+Keylock, C. J. (2005) Simpson diversity and the Shannon-Wiener index as special cases of a generalized entropy.
+  \emph{Oikos} \bold{109}, 203--207.
+
+Jost, L (2007) Partitioning diversity into independent alpha and beta components.
+  \emph{Ecology} \bold{88}, 2427--2439.
 }
 \author{\enc{P\'eter S\'olymos}{Peter Solymos}, \email{solymos at ualberta.ca}, based on the code of Roeland Kindt and Jari Oksanen written for \code{renyi}}
 \seealso{