[Vegan-commits] r1835 - in pkg/vegan: . R inst man tests/Examples
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sat Sep 10 16:18:00 CEST 2011
Author: jarioksa
Date: 2011-09-10 16:17:59 +0200 (Sat, 10 Sep 2011)
New Revision: 1835
Added:
pkg/vegan/R/raupcrick.R
pkg/vegan/man/raupcrick.Rd
Modified:
pkg/vegan/NAMESPACE
pkg/vegan/inst/ChangeLog
pkg/vegan/man/designdist.Rd
pkg/vegan/man/oecosimu.Rd
pkg/vegan/man/vegdist.Rd
pkg/vegan/tests/Examples/vegan-Ex.Rout.save
Log:
implement Raup-Crick dissimilarity with sampling probabilities of species proportional to frequency (like Brian Inouye told us to do)
Modified: pkg/vegan/NAMESPACE
===================================================================
--- pkg/vegan/NAMESPACE 2011-09-10 06:16:55 UTC (rev 1834)
+++ pkg/vegan/NAMESPACE 2011-09-10 14:17:59 UTC (rev 1835)
@@ -22,7 +22,7 @@
pcnm, permatfull, permatswap, permatfull1, permatswap1,
permutest, poolaccum, postMDS, prc,
prestondistr, prestonfit, procrustes, protest, radfit, radlattice,
-rankindex, rarefy, rda, renyiaccum, renyi, rrarefy, scores,
+rankindex, rarefy,raupcrick, rda, renyiaccum, renyi, rrarefy, scores,
showvarparts, spandepth, spantree, specaccum, specnumber,
specpool2vect, specpool, spenvcor, stepacross, stressplot, swan,
taxa2dist, taxondive, tolerance, treedist, treedive, treeheight,
Added: pkg/vegan/R/raupcrick.R
===================================================================
--- pkg/vegan/R/raupcrick.R (rev 0)
+++ pkg/vegan/R/raupcrick.R 2011-09-10 14:17:59 UTC (rev 1835)
@@ -0,0 +1,27 @@
+`raupcrick` <-
+ function(comm, null = "r1", nsimul = 999, chase = FALSE)
+{
+ comm <- as.matrix(comm)
+ comm <- ifelse(comm > 0, 1, 0)
+ ## 'tri' is a faster alternative to as.dist(): it takes the lower
+ ## diagonal, but does not set attributes of a "dist" object
+ N <- nrow(comm)
+ tri <- matrix(FALSE, N, N)
+ tri <- row(tri) > col(tri)
+ ## function(x) designdist(x, "J", terms="binary") does the same,
+ ## but is much slower
+ sol <- oecosimu(comm, function(x) tcrossprod(x)[tri], method = null,
+ nsimul = nsimul,
+ alternative = if (chase) "greater" else "less")
+ ## Chase et al. way, or the standard way
+ if (chase)
+ out <- 1 - sol$oecosimu$pval
+ else
+ out <- sol$oecosimu$pval
+ ## set attributes of a "dist" object
+ attributes(out) <- list("class"=c("raupcrick", "dist"), "Size"=N,
+ "Labels" = rownames(comm), "call" =
+ match.call(), "Diag" = FALSE, "Upper" = FALSE,
+ "method" = "raupcrick")
+ out
+}
Modified: pkg/vegan/inst/ChangeLog
===================================================================
--- pkg/vegan/inst/ChangeLog 2011-09-10 06:16:55 UTC (rev 1834)
+++ pkg/vegan/inst/ChangeLog 2011-09-10 14:17:59 UTC (rev 1835)
@@ -19,19 +19,32 @@
in other parts. With faster C code the net slowdown is 1.7x.
* New functions: permatfull1 and permatswap1. Both functions
- return a single permuted matrix. These functions are now
- called repeatedly by the corresponding permatfull and permatswap
+ return a single permuted matrix. These functions are now calledino
+ 絵
+ repeatedly by the corresponding permatfull and permatswap
functions.
- * New function: clamtest (with summary and plot methods).
- The method uses a multinomial model based on estimated species
- relative abundance in two habitats, it minimizes bias
- due to differences in sampling intensities between two
- habitat types as well as bias due to insufficient sampling within each
- habitat. The method permits a robust statistical classification
- of habitat specialists and generalists, without excluding rare
- species a priori. Based on Chazdon et al. 2011 (Ecology, 92, 1332--1343).
+ * New function: clamtest (with summary and plot methods). The
+ method uses a multinomial model based on estimated species
+ relative abundance in two habitats, it minimizes bias due to
+ differences in sampling intensities between two habitat types as
+ well as bias due to insufficient sampling within each habitat. The
+ method permits a robust statistical classification of habitat
+ specialists and generalists, without excluding rare species a
+ priori. Based on Chazdon et al. 2011 (Ecology, 92, 1332--1343).
+ * raupcrick: new function to implement Raup-Crick (dissimilarity/
+ probability) index with unequal sampling probabilities of species.
+ Brian Inouye informed about their paper (Chase et al., Ecospher
+ 2:art24 [doi:10.1890/ES10-00117.1]; 2011) where they showed that
+ Raup & Crick said that we should use sampling probabilities
+ proportional to species frequencies in assessing their index, but
+ vegdist(x, "raup") uses equal probabilities. Unequal sampling
+ probabilities cannot be directly implemented in vegan, but the
+ Chase et al. method can be implemented as oecosimu(x, function(x)
+ designdist(x, "J"), method="r1"). Basically, the current function
+ uses this, but with boosted code that is much faster than
+ designdist().
Version 2.0-0 (released September 8, 2011)
Modified: pkg/vegan/man/designdist.Rd
===================================================================
--- pkg/vegan/man/designdist.Rd 2011-09-10 06:16:55 UTC (rev 1834)
+++ pkg/vegan/man/designdist.Rd 2011-09-10 14:17:59 UTC (rev 1835)
@@ -59,7 +59,7 @@
\code{1-J/sqrt(A*B)} \tab \code{"binary"} \tab Ochiai \cr
\code{1-J/sqrt(A*B)} \tab \code{"quadratic"} \tab cosine
complement \cr
- \code{1-phyper(J-1, A, P-A, B)} \tab \code{"binary"} \tab Raup-Crick
+ \code{1-phyper(J-1, A, P-A, B)} \tab \code{"binary"} \tab Raup-Crick (but see \code{\link{raupcrick}})
}
The function \code{designdist} can implement most dissimilarity
Modified: pkg/vegan/man/oecosimu.Rd
===================================================================
--- pkg/vegan/man/oecosimu.Rd 2011-09-10 06:16:55 UTC (rev 1834)
+++ pkg/vegan/man/oecosimu.Rd 2011-09-10 14:17:59 UTC (rev 1835)
@@ -58,21 +58,23 @@
\details{
Function \code{oecosimu} is a wrapper that evaluates a nestedness
- statistic using function given by \code{nestfun}, and then simulates a
- series of null models using \code{commsimulator} or
- other functions (depending on method argument), and evaluates the
- statistic on these null models. The \pkg{vegan} packages contains some
- nestedness functions that are described separately
+ statistic using function given by \code{nestfun}, and then simulates
+ a series of null models using \code{commsimulator} or other
+ functions (depending on method argument), and evaluates the
+ statistic on these null models. The \pkg{vegan} packages contains
+ some nestedness functions that are described separately
(\code{\link{nestedchecker}}, \code{\link{nesteddisc}},
\code{\link{nestedn0}}, \code{\link{nestedtemp}}), but many other
- functions can be used as long as they are meaningful with binary
- or quantitative community models. An applicable function must return either the
- statistic as a plain number, or as a list element \code{"statistic"}
- (like \code{\link{chisq.test}}), or in an item whose name is given in
- the argument \code{statistic}. The statistic can be a single number
- (like typical for a nestedness index), or it can be a vector. The
- vector indices can be used to analyse site (row) or species (column)
- properties, see \code{\link{treedive}} for an example.
+ functions can be used as long as they are meaningful with binary or
+ quantitative community models. An applicable function must return
+ either the statistic as a plain number, or as a list element
+ \code{"statistic"} (like \code{\link{chisq.test}}), or in an item
+ whose name is given in the argument \code{statistic}. The statistic
+ can be a single number (like typical for a nestedness index), or it
+ can be a vector. The vector indices can be used to analyse site
+ (row) or species (column) properties, see \code{\link{treedive}} for
+ an example. Raup-Crick index (\code{\link{raupcrick}}) gives an
+ example of using a dissimilarities index.
Function \code{commsimulator} implements binary (presence/absence)
null models for community composition.
Added: pkg/vegan/man/raupcrick.Rd
===================================================================
--- pkg/vegan/man/raupcrick.Rd (rev 0)
+++ pkg/vegan/man/raupcrick.Rd 2011-09-10 14:17:59 UTC (rev 1835)
@@ -0,0 +1,115 @@
+\name{raupcrick}
+\alias{raupcrick}
+
+\title{
+ Raup-Crick Dissimilarity with Unequal Sampling Densities of Species
+}
+
+\description{ Function finds the Raup-Crick dissimilarity which is a
+ probability index of number of co-occuring species with species
+ occurrence probability proportional to species frequencies.
+}
+
+\usage{
+raupcrick(comm, null = "r1", nsimul = 999, chase = FALSE)
+}
+
+\arguments{
+
+ \item{comm}{Community data which will be treated as presence/absence data.}
+
+ \item{null}{Null model used as the \code{method} in
+ \code{\link{oecosimu}}.}
+
+ \item{nsimul}{Number of null communities for assessing the
+ dissimilarity index.}
+
+ \item{chase}{Use the Chase et al. (2011) method of tie handling (not
+ recommended except for comparing the results against the Chase
+ script).}
+
+}
+
+\details{Raup-Crick index is the probability that compared sampling
+ units have identical species composition. This probability can be
+ regarded as a dissimilarity, although it is not metric: identical
+ sampling units can have dissimilarity slightly above \eqn{0}, and
+ sampling units with no shared species can have dissimilarity below
+ \eqn{1}. Moreover, communities sharing rare species appear as more
+ similar (lower probability of finding rare species together), than
+ communities sharing the same number of common species.
+
+ The function will always treat the data as binary (presence/ absence).
+
+ The probability is assessed using simulation with
+ \code{\link{oecosimu}} where the test statistic is the observed
+ number of shared species between sampling units (see Examples).
+ Simulation is performed using an \code{\link{oecosimu}} \code{null}
+ model. The default null model is \code{"r1"} where the probability
+ of selecting species is proportional to the species frequencies.
+
+ The \code{\link{vegdist}} function implements a variant of the
+ Raup-Crick index with equal sampling densities for species using
+ exact analytic equations without simulation. This corresponds to
+ \code{null} model \code{"r0"} which also can be used with the
+ current function. All other null model methods of
+ \code{\link{oecosimu}} can be used with the current function, but
+ they are new unpublished methods.
+}
+
+\value{The function returns an object inheriting from
+ \code{\link{dist}} which can be interpreted as a dissimilarity
+ matrix.}
+
+\references{
+ 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]
+}
+
+\author{The function was developed after Brian Inouye contacted us and
+ informed us about the method in Chase et al. (2011), and the
+ function takes its idea from the code that was publisehd with their
+ paper. The current function was written by Jari Oksanen. }
+
+\note{Function \code{rauprcrick} with options \code{null = "r1"} and
+ \code{split = TRUE} gives equal results (within sampling error) to
+ the function published with Chase et al. (2011) when their function
+ is called with argument \code{split = FALSE}. However, \code{chase =
+ TRUE} is not recommended except for this comparison. In
+ \code{raupcrick} (\pkg{vegan}) simulation values tied with the
+ observed test statistic do not prove against the null model, unlike
+ in the Chase et al. (2011) script with \code{split = FALSE}. The
+ Chase et al. (2011) script with \code{split = TRUE} regards a half
+ of tied simulation values to support and a half to oppose the null
+ model, and that choice cannot be reproduced in \pkg{vegan}.}
+
+\seealso{The function is based on \code{\link{oecosimu}}. Function
+ \code{\link{vegdist}} with {method = "raup"} implements a related
+ index but with equal sampling densities of species, and
+ \code{\link{designdist}} demonstrates its calculation.}
+
+\examples{
+## data set with variable species richness
+data(sipoo)
+## default raupcrick
+dr1 <- raupcrick(sipoo)
+## use null model "r0" of oecosimu
+dr0 <- raupcrick(sipoo, null = "r0")
+## vegdist(..., method = "raup") corresponds to 'null = "r0"'
+d <- vegdist(sipoo, "raup")
+op <- par(mfrow=c(2,1), mar=c(4,4,1,1)+.1)
+plot(dr1 ~ d, xlab = "Raup-Crick with Null R1", ylab="vegdist")
+plot(dr0 ~ d, xlab = "Raup-Crick with Null R0", ylab="vegdist")
+par(op)
+
+## The calculation is essentially as in the following oecosimu() call,
+## except that designdist() is replaced with faster code
+\dontrun{%
+oecosimu(sipoo, function(x) designdist(x, "J", "binary"), method = "r1")
+}
+}
+
+\keyword{ multivariate }
+
Modified: pkg/vegan/man/vegdist.Rd
===================================================================
--- pkg/vegan/man/vegdist.Rd 2011-09-10 06:16:55 UTC (rev 1834)
+++ pkg/vegan/man/vegdist.Rd 2011-09-10 14:17:59 UTC (rev 1835)
@@ -163,10 +163,12 @@
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.
+ zero. The index uses equal occurrence probabilities for all species,
+ but Raup and Crick originally suggested that sampling probabilities
+ should be proportional to species frequencies (Chase et al. 2011). A
+ simulation approach with unequal species sampling probabilities is
+ implemented in \code{\link{raupcrick}} function following Chase et
+ al. (2011).
Chao index tries to take into account the number of unseen species
pairs, similarly as in \code{method = "chao"} in
Modified: pkg/vegan/tests/Examples/vegan-Ex.Rout.save
===================================================================
--- pkg/vegan/tests/Examples/vegan-Ex.Rout.save 2011-09-10 06:16:55 UTC (rev 1834)
+++ pkg/vegan/tests/Examples/vegan-Ex.Rout.save 2011-09-10 14:17:59 UTC (rev 1835)
@@ -161,7 +161,7 @@
Formula:
y ~ poly(x1, 1) + poly(x2, 1)
-<environment: 0x100ed4a30>
+<environment: 0x100edc878>
Total model degrees of freedom 3
GCV score: 0.0427924
@@ -4819,7 +4819,7 @@
Formula:
y ~ s(x1, x2, k = knots)
-<environment: 0x1069dabf8>
+<environment: 0x106b4df48>
Estimated degrees of freedom:
6.4351 total = 7.435071
@@ -4835,7 +4835,7 @@
Formula:
y ~ s(x1, x2, k = knots)
-<environment: 0x107e2dcd0>
+<environment: 0x107b6a898>
Estimated degrees of freedom:
6.1039 total = 7.103853
@@ -4991,7 +4991,7 @@
Formula:
y ~ s(x1, x2, k = knots)
-<environment: 0x104d0f628>
+<environment: 0x1060c2d18>
Estimated degrees of freedom:
8.9275 total = 9.927492
@@ -5004,7 +5004,7 @@
Formula:
y ~ s(x1, x2, k = knots)
-<environment: 0x107b42078>
+<environment: 0x106942d50>
Estimated degrees of freedom:
7.7529 total = 8.75294
@@ -5017,7 +5017,7 @@
Formula:
y ~ s(x1, x2, k = knots)
-<environment: 0x10788b580>
+<environment: 0x107c3ce98>
Estimated degrees of freedom:
8.8962 total = 9.89616
@@ -5911,6 +5911,42 @@
>
>
> cleanEx()
+> nameEx("raupcrick")
+> ### * raupcrick
+>
+> flush(stderr()); flush(stdout())
+>
+> ### Name: raupcrick
+> ### Title: Raup-Crick Dissimilarity with Unequal Sampling Densities of
+> ### Species
+> ### Aliases: raupcrick
+> ### Keywords: multivariate
+>
+> ### ** Examples
+>
+> ## data set with variable species richness
+> data(sipoo)
+> ## default raupcrick
+> dr1 <- raupcrick(sipoo)
+> ## use null model "r0" of oecosimu
+> dr0 <- raupcrick(sipoo, null = "r0")
+> ## vegdist(..., method = "raup") corresponds to 'null = "r0"'
+> d <- vegdist(sipoo, "raup")
+> op <- par(mfrow=c(2,1), mar=c(4,4,1,1)+.1)
+> plot(dr1 ~ d, xlab = "Raup-Crick with Null R1", ylab="vegdist")
+> plot(dr0 ~ d, xlab = "Raup-Crick with Null R0", ylab="vegdist")
+> par(op)
+>
+> ## The calculation is essentially as in the following oecosimu() call,
+> ## except that designdist() is replaced with faster code
+> ## Not run: ##D
+> ##D oecosimu(sipoo, function(x) designdist(x, "J", "binary"), method = "r1")
+> ## End(Not run)
+>
+>
+>
+> graphics::par(get("par.postscript", pos = 'CheckExEnv'))
+> cleanEx()
> nameEx("read.cep")
> ### * read.cep
>
@@ -7241,7 +7277,7 @@
Formula:
y ~ s(x1, x2, k = knots)
-<environment: 0x106abe778>
+<environment: 0x1067a70e0>
Estimated degrees of freedom:
2 total = 3
@@ -7717,7 +7753,7 @@
> ### * <FOOTER>
> ###
> cat("Time elapsed: ", proc.time() - get("ptime", pos = 'CheckExEnv'),"\n")
-Time elapsed: 140.127 1.72 143.859 0 0
+Time elapsed: 169.337 2.16 177.451 0 0
> grDevices::dev.off()
null device
1
More information about the Vegan-commits
mailing list