[Vegan-commits] r256 - in pkg: R inst man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sat Mar 8 17:20:20 CET 2008
Author: jarioksa
Date: 2008-03-08 17:20:20 +0100 (Sat, 08 Mar 2008)
New Revision: 256
Added:
pkg/R/betadiver.R
pkg/R/plot.betadiver.R
pkg/R/scores.betadiver.R
pkg/man/betadiver.Rd
Modified:
pkg/inst/ChangeLog
pkg/man/betadisper.Rd
pkg/man/designdist.Rd
pkg/man/vegdist.Rd
Log:
Added indices of beta diversity (betadiver.R with associated functions)
Added: pkg/R/betadiver.R
===================================================================
--- pkg/R/betadiver.R (rev 0)
+++ pkg/R/betadiver.R 2008-03-08 16:20:20 UTC (rev 256)
@@ -0,0 +1,47 @@
+`betadiver` <-
+ function(x, index = NA, order = FALSE, help = FALSE, ...)
+{
+ beta <- list("w"="(b+c)/(2*a+b+c)", "-1"="(b+c)/(2*a+b+c)", "c"="(b+c)/2",
+ "wb"="b+c", "r"="2*b*c/((a+b+c)^2-2*b*c)",
+ "I"="log(2*a+b+c)-2*a*log(2)/(2*a+b+c)-((a+b)*log(a+b)+(a+c)*log(a+c))/(2*a+b+c)",
+ "e"="exp(log(2*a+b+c)-2*a*log(2)/(2*a+b+c)-((a+b)*log(a+b)+(a+c)*log(a+c))/(2*a+b+c))-1",
+ "t"="(b+c)/(2*a+b+c)", "me"="(b+c)/(2*a+b+c)",
+ "j"="a/(a+b+c)", "sor"="2*a/(2*a+b+c)",
+ "m"="(2*a+b+c)*(b+c)/(a+b+c)",
+ "-2"="pmin(b,c)/(pmax(b,c)+a)",
+ "co"="(a*c+a*b+2*b*c)/(2*(a+b)*(a+c))",
+ "cc"="(b+c)/(a+b+c)", "g"="(b+c)/(a+b+c)",
+ "-3"="pmin(b,c)/(a+b+c)", "l"="(b+c)/2",
+ "19"="2*(b*c+1)/((a+b+c)^2+(a+b+c))",
+ "hk"="(b+c)/(2*a+b+c)", "rlb"="a/(a+c)",
+ "sim"="pmin(b,c)/(pmin(b,c)+a)",
+ "gl"="2*abs(b-c)/(2*a+b+c)",
+ "z"="(log(2)-log(2*a+b+c)+log(a+b+c))/log(2)"
+ )
+ if (help) {
+ for (i in 1:length(beta))
+ cat(i, dQuote(names(beta[i])),"=", beta[[i]], "\n")
+ return(invisible(NULL))
+ }
+ x <- ifelse(x > 0, 1, 0)
+ if (order) {
+ x <- x[order(rowSums(x)),]
+ }
+ d <- tcrossprod(x)
+ a <- as.dist(d)
+ S <- diag(d)
+ N <- length(S)
+ b <- as.dist(matrix(rep(S, N), nrow=N)) - a
+ c <- as.dist(matrix(rep(S, each=N), nrow=N)) - a
+ if (is.na(index) || is.null(index) || is.logical(index) && !index) {
+ out <- list(a = a, b = b, c = c)
+ class(out) <- "betadiver"
+ return(out)
+ }
+ out <- eval(parse(text=beta[[index]]))
+ out <- as.dist(out)
+ attr(out, "method") <- paste("beta", names(beta[index]), sep=".")
+ attr(out, "call") <- match.call()
+ out
+}
+
Added: pkg/R/plot.betadiver.R
===================================================================
--- pkg/R/plot.betadiver.R (rev 0)
+++ pkg/R/plot.betadiver.R 2008-03-08 16:20:20 UTC (rev 256)
@@ -0,0 +1,18 @@
+`plot.betadiver` <-
+ function(x, ...)
+{
+ xy <- scores(x, ...)
+ plot(c(0,1),c(0,sqrt(0.75)), type="n", axes=FALSE, xlab="", ylab="",
+ asp=1)
+ for(tic in seq(0.2,0.8, by=0.2)) {
+ segments(tic, 0, tic/2 , sqrt(0.75)*tic, lty=3)
+ segments(tic/2, sqrt(0.75)*tic, 1-tic/2, sqrt(0.75)*tic, lty=3)
+ segments(tic, 0, tic/2+0.5, sqrt(0.75)*(1-tic), lty=3)
+ }
+ text(c(0,1,0.5), c(0,0,sqrt(0.75)), c("b'","c'","a'"), pos=c(2,4,3),
+ cex=par("cex.axis"))
+ lines(c(0,1,0.5,0), c(0,0,sqrt(0.75),0), xpd=TRUE)
+ points(xy, ...)
+ invisible(xy)
+}
+
Added: pkg/R/scores.betadiver.R
===================================================================
--- pkg/R/scores.betadiver.R (rev 0)
+++ pkg/R/scores.betadiver.R 2008-03-08 16:20:20 UTC (rev 256)
@@ -0,0 +1,11 @@
+`scores.betadiver` <-
+ function(x, ...)
+{
+ tot <- x$a + x$b + x$c
+ a <- x$a/tot
+ c <- x$c/tot
+ y <- sqrt(0.75)*a
+ x <- c + a/2
+ cbind(x, y)
+}
+
Modified: pkg/inst/ChangeLog
===================================================================
--- pkg/inst/ChangeLog 2008-03-07 10:46:33 UTC (rev 255)
+++ pkg/inst/ChangeLog 2008-03-08 16:20:20 UTC (rev 256)
@@ -2,8 +2,12 @@
VEGAN DEVEL VERSIONS at http://r-forge.r-project.org/
-Version 1.2-3 (Mar 7, 2008)
+Version 1.2-3 (Mar 8, 2008, working...)
+ * betadiver: a new function that implements all indices of beta
+ diversity reviewed by Koleff et al. (J. Anim. Ecol., 72, 367-382;
+ 2003), with a plot function to produce triangular plots.
+
* isomap: added dynamic, spinnable 3D graphics using rgl
(rgl.isomap).
Modified: pkg/man/betadisper.Rd
===================================================================
--- pkg/man/betadisper.Rd 2008-03-07 10:46:33 UTC (rev 255)
+++ pkg/man/betadisper.Rd 2008-03-08 16:20:20 UTC (rev 256)
@@ -32,10 +32,11 @@
\method{boxplot}{betadisper}(x, ylab = "Distance to centroid", ...)
}
-%- maybe also 'usage' for other objects documented here.
+
\arguments{
- \item{d}{a distance structure such as that returned by
- \code{\link[stats]{dist}} or \code{\link{vegdist}}.}
+ \item{d}{a distance structure such as that returned by
+ \code{\link[stats]{dist}}, \code{link{betadiver}} or
+ \code{\link{vegdist}}.}
\item{group}{vector describing the group structure, usually a factor
or an object that can be coerced to a factor using
\code{\link[base]{as.factor}}.}
@@ -90,7 +91,8 @@
and \code{boxplot} methods.
One additional use of these functions is in assessing beta diversity
- (Anderson \emph{et al} 2006).
+ (Anderson \emph{et al} 2006). Function \code{\link{betadiver}}
+ provides some popular dissimilarity measures for this purpose.
}
\value{
The \code{anova} method returns an object of class \code{"anova"}
@@ -137,7 +139,7 @@
}
\author{Gavin L. Simpson}
\seealso{\code{\link[stats]{anova.lm}}, \code{\link{scores}},
- \code{\link[graphics]{boxplot}}}
+ \code{\link[graphics]{boxplot}}, \code{\link{betadiver}}.}
\examples{
data(varespec)
Added: pkg/man/betadiver.Rd
===================================================================
--- pkg/man/betadiver.Rd (rev 0)
+++ pkg/man/betadiver.Rd 2008-03-08 16:20:20 UTC (rev 256)
@@ -0,0 +1,121 @@
+\encoding{UTF-8}
+\name{betadiver}
+\alias{betadiver}
+\alias{scores.betadiver}
+\alias{plot.betadiver}
+
+\title{ Indices of beta Diversity }
+\description{
+ The function estimates any of the 24 indices of beta diversity
+ reviewed by Koleff et al. (2003). Alternatively, it finds the
+ co-occurrence frequencies for triangular plots (Koleff et
+ al. 2003).
+}
+
+\usage{
+betadiver(x, index = NA, order = FALSE, help = FALSE, ...)
+\method{plot}{betadiver}(x, ...)
+\method{scores}{betadiver}(x, ...)
+}
+
+\arguments{
+ \item{x}{Community data matrix, or the \code{betadiver} result for
+ \code{plot} and \code{scores} functions. }
+ \item{index}{The index of beta diversity as defined in Koleff et al.
+ (2003), Table 1. You can use either the subscript of \eqn{\beta} or
+ the number of the index. See argument \code{help} below. }
+ \item{order}{Order sites by increasing number of species. This will
+ influence the configuration in the triangular plot and non-symmetric
+ indices. }
+ \item{help}{Show the numbers, subscript names and the defining
+ equations of the indices and exit.}
+ \item{\dots}{ Other arguments to functions. }
+}
+
+\details{
+ The most commonly used index of beta diversity is \eqn{\beta_w =
+ S/\alpha - 1}, where \eqn{S} is the total number of species, and
+ \eqn{\alpha} is the average number of species per site (Whittaker
+ 1960). A drawback of this model is that \eqn{S} increases with
+ sample size, but the expectation of \eqn{\alpha} remains constant,
+ and so the beta diversity increases with sample size. A solution to
+ this problem is to study the beta diversity of pairs of sites. If we
+ denote the number of species shared between two sites as \eqn{a} and
+ the numbers of unique species (not shared) as \eqn{b} and \eqn{c},
+ then \eqn{S = a + b + c} and \eqn{\alpha = (2 a + b + c)/2} so that
+ \eqn{\beta_w = (b+c)/(2 a + b + c)}. This is the Sorensen
+ dissimilarity as defined in \pkg{vegan} function
+ \code{\link{vegdist}} with argument \code{binary = TRUE}. Many
+ other indices also are dissimilarity indices.
+
+ Function \code{betadiver} finds all indices reviewed by Koleff et
+ al. (2003). All these indices could be found with function
+ \code{\link{designdist}} which uses different notation, but the
+ current function provides a conventional shortcut. The function
+ only finds the indices. The proper analysis must be done with
+ functions such as \code{\link{betadisper}}, \code{\link{adonis}} or
+ \code{\link{mantel}}.
+
+ The indices are directly taken from Table 1 of Koleff et
+ al. (2003). The function can be selected either by the index number
+ or the subscript name used by Koleff et al. (2003). The numbers,
+ names and defining equations can be seen using \code{betadiver(help
+ = TRUE)}. In all cases where there are two alternative forms, the
+ one with the term \eqn{-1} is used. There are several duplicate
+ indices, and the number of distinct alternatives is much lower than
+ 24 formally provided. The formulations used in functions differ
+ occasionally from those in Koleff et al. (2003), but they are still
+ mathematically equivalent. With \code{index = NA}, no index
+ is calculated, but instead an object of class \code{betadiver} is
+ returned. This is a list of elements \code{a}, \code{b} and
+ \code{c}. Function \code{plot} can be used to display the
+ proportions of these elements in triangular plot as suggested by
+ Koleff et al. (2003), and \code{scores} extracts the triangular
+ coordinates. Function \code{plot} returns invisibly the triangular
+ coordinates. }
+
+\value{ With \code{index = NA}, the function returns an object of
+ class \code{"betadisper"} with elements \code{a}, \code{b}, and
+ \code{c}. If \code{index} is specified, the function returns a
+ \code{"dist"} object which can be used in any function analysing
+ dissimilarities. For beta diversity, particularly useful functions
+ are \code{\link{betadisper}} to study the betadiversity in groups,
+ \code{\link{adonis}} for any model, and \code{\link{mantel}} to
+ compare beta diversities to other dissimilarities or distances
+ (including geographical distances). Although \code{betadiver}
+ returns a \code{"dist"} object, some indices are similarities and
+ cannot be used as such in place of dissimilarities, but that is a
+ severe user error. Functions 10 (\code{"j"}) and 11 (\code{"sor"})
+ are two such similarity indices. }
+
+\references{
+Koleff, P., Gaston, K.J. and Lennon, J.J. (2003) Measuring beta
+diversity for presence-absence data. \emph{Journal of Animal Ecology}
+72, 367--382.
+
+Whittaker, R.H. (1960) Vegetation of Siskiyou mountains, Oregon and
+ California. \emph{Ecological Monographs} 30, 279--338.
+ }
+\author{Jari Oksanen }
+\section{Warning }{Some indices return similarities instead of dissimilarities.}
+
+\seealso{ \code{\link{designdist}} for an alternative to implement all
+these functions, \code{\link{vegdist}} for some canned alternatives,
+and \code{\link{betadisper}}, \code{\link{adonis}},
+\code{\link{mantel}} for analysing beta diversity objects.}
+\examples{
+## Raw data and plotting
+data(sipoo)
+m <- betadiver(sipoo)
+plot(m)
+## The indices
+betadiver(help=TRUE)
+## The basic Whittaker index
+d <- betadiver(sipoo, "w")
+## This should be equal to Sorensen index (binary Bray-Curtis in
+## vegan)
+range(d - vegdist(sipoo, binary=TRUE))
+}
+
+\keyword{ multivariate }
+
Modified: pkg/man/designdist.Rd
===================================================================
--- pkg/man/designdist.Rd 2008-03-07 10:46:33 UTC (rev 255)
+++ pkg/man/designdist.Rd 2008-03-08 16:20:20 UTC (rev 256)
@@ -62,7 +62,8 @@
used to implement many other indices, amongst them, most of those
described in Legendre & Legendre (1998). It can also be used to
implement all indices of beta diversity described in Koleff et
- al. (2003).
+ al. (2003), but there also is a specific function
+ \code{\link{betadiver}} for the purpose.
If you want to implement binary dissimilarities based on the 2x2
contingency table notation, then \eqn{a =} \code{J}, \eqn{b =}
@@ -88,7 +89,7 @@
function using compiled code, it is better to use the canned
alternative.
}
-\seealso{ \code{\link{vegdist}}, \code{\link{dist}}. }
+\seealso{ \code{\link{vegdist}}, \code{\link{betadiver}}, \code{\link{dist}}. }
\examples{
## Arrhenius dissimilarity: the value of z in the species-area model
## S = c*A^z when combining two sites of equal areas, where S is the
Modified: pkg/man/vegdist.Rd
===================================================================
--- pkg/man/vegdist.Rd 2008-03-07 10:46:33 UTC (rev 255)
+++ pkg/man/vegdist.Rd 2008-03-08 16:20:20 UTC (rev 256)
@@ -244,7 +244,9 @@
dissimilarity index. Alternative dissimilarity functions include
\code{\link{dist}} in base \R,
\code{\link[cluster]{daisy}} (package \pkg{cluster}), and
- \code{\link[labdsv]{dsvdis}} (package \pkg{labdsv}). }
+ \code{\link[labdsv]{dsvdis}} (package \pkg{labdsv}). Function
+ \code{\link{betadiver}} provides indices intended for the analysis of
+ beta diversity.}
\examples{
data(varespec)
More information about the Vegan-commits
mailing list