[Vegan-commits] r681 - in pkg/vegan: R man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Mon Feb 9 07:50:24 CET 2009
Author: psolymos
Date: 2009-02-09 07:50:24 +0100 (Mon, 09 Feb 2009)
New Revision: 681
Added:
pkg/vegan/R/contribdiv.R
pkg/vegan/R/plot.contribdiv.R
pkg/vegan/man/contribdiv.Rd
Log:
contribdiv function based on Lu et al 2007 added, documentation needs
more work
Added: pkg/vegan/R/contribdiv.R
===================================================================
--- pkg/vegan/R/contribdiv.R (rev 0)
+++ pkg/vegan/R/contribdiv.R 2009-02-09 06:50:24 UTC (rev 681)
@@ -0,0 +1,51 @@
+## Contribution diversity
+## Lu, H.P., H.H. Wagner and X.Y. Chen (2007).
+## A contribution diversity approach to evaluate species diversity.
+## Basic and Applied Ecology 8: 1 -12.
+contribdiv <-
+function(comm, index = c("richness", "simpson"), relative = FALSE, scaled = TRUE, drop.zero = FALSE)
+{
+
+ index <- match.arg(index)
+
+ x <- comm[rowSums(comm) > 0, colSums(comm) > 0]
+ n <- nrow(x)
+ S <- ncol(x)
+
+ if (index == "richness") {
+ n.i <- colSums(x > 0)
+ S.k <- rowSums(x > 0)
+ alpha <- S.k / n
+ beta <- apply(x, 1, function(z) sum((n - n.i[z > 0]) / (n * n.i[z > 0])))
+ denom <- 1
+ } else {
+ P.ik <- decostand(x, "total")
+ P.i <- apply(P.ik, 2, function(z) sum(z) / n)
+ P.i2 <- matrix(P.i, n, S, byrow=TRUE)
+ alpha <- diversity(x, "simpson")
+ beta <- rowSums(P.ik * (P.ik - P.i2))
+ denom <- n
+ }
+ gamma <- alpha + beta
+ D <- sum(beta) / sum(gamma)
+ if (relative) {
+ denom <- if (scaled)
+ {denom * sum(gamma)} else 1
+ alpha <- (alpha - mean(alpha)) / denom
+ beta <- (beta - mean(beta)) / denom
+ gamma <- (gamma - mean(gamma)) / denom
+ }
+ rval <- data.frame(alpha = alpha, beta = beta, gamma = gamma)
+ if (!drop.zero && nrow(comm) != n) {
+ nas <- rep(NA, nrow(comm))
+ rval2 <- data.frame(alpha = nas, beta = nas, gamma = nas)
+ rval2[rowSums(comm) > 0, ] <- rval
+ rval <- rval2
+ }
+ attr(rval, "diff.coef") <- D
+ attr(rval, "index") <- index
+ attr(rval, "relative") <- relative
+ attr(rval, "scaled") <- scaled
+ class(rval) <- c("contribdiv", "data.frame")
+ return(rval)
+}
Added: pkg/vegan/R/plot.contribdiv.R
===================================================================
--- pkg/vegan/R/plot.contribdiv.R (rev 0)
+++ pkg/vegan/R/plot.contribdiv.R 2009-02-09 06:50:24 UTC (rev 681)
@@ -0,0 +1,18 @@
+plot.contribdiv <-
+function(x, sub, xlab, ylab, ylim, col, ...) {
+ y <- x[,c(1,3)]
+ if (missing(ylab))
+ ylab <- paste("Diversity components (", attr(x, "index"), ")", sep = "")
+ if (missing(xlab))
+ xlab <- "Sites"
+ if (missing(sub))
+ sub <- paste("Differentiation coefficient = ", round(attr(x, "diff.coef"),3), sep = "")
+ if (missing(ylim))
+ ylim <- c(0, max(y))
+ if (missing(col))
+ col <- c("lightgrey", "darkgrey")
+ matplot(y, type = "n", sub=sub,xlab=xlab,ylab=ylab,...)
+ polygon(c(1,1:nrow(y),nrow(y)), c(0,y$gamma,0), col=col[1])
+ polygon(c(1,1:nrow(y),nrow(y)), c(0,y$alpha,0), col=col[2])
+ invisible(x)
+}
Added: pkg/vegan/man/contribdiv.Rd
===================================================================
--- pkg/vegan/man/contribdiv.Rd (rev 0)
+++ pkg/vegan/man/contribdiv.Rd 2009-02-09 06:50:24 UTC (rev 681)
@@ -0,0 +1,68 @@
+\encoding{UTF-8}
+\name{contribdiv}
+\alias{contribdiv}
+\alias{plot.contribdiv}
+\title{Contribution Diversity Approach}
+\description{
+The contribution diversity approach is based in the differentiation of within-unit and among-unit diversity by using additive diversity partitioning and unit distinctiveness.
+}
+\usage{
+contribdiv(comm, index = c("richness", "simpson"),
+relative = FALSE, scaled = TRUE, drop.zero = FALSE)
+\method{plot}{contribdiv}(x, sub, xlab, ylab, ylim, col, ...)
+}
+\arguments{
+ \item{comm}{The community data matrix with samples as rows and species as column.}
+ \item{index}{Character, the diversity index to be calculated.}
+ \item{relative}{Logical, if \code{TRUE} then contribution diversity values are expressed as their signed deviation from their mean. See details.}
+ \item{scaled}{Logical, if \code{TRUE} then relative contribution diversity values are scaled by the sum of gamma values (if \code{index = "richness"}) or by sum of gamma values times the number of rowx in \code{comm} (if \code{index = "simpson"}). See details.}
+ \item{drop.zero}{Logical, should empty rows dropped from the result? If empty rows are not dropped, their corresponding results will be \code{NA}s.}
+ \item{x}{An object of class 'contribdiv'.}
+ \item{sub, xlab, ylab, ylim, col}{Graphical arguments passed to plot.}
+ \item{\dots}{Other arguments passed to plot.}
+}
+\details{
+This approach was proposed by Lu et al. (2007). Additive diversity partitioning (see \code{\link{adipart}} for more references) deals with the relation of mean alpha and the total (gamma) diversity. Although alpha diversity values are often vary considerably. Thus, contributions of the sites to the total diversity are uneven. This site specific contribution is measured by contribution diversity components. A unit that has e.g. many unique species will contribute more to the higher level (gamma) diversity than another unit with the same number of species, but all of which common.
+
+Species distinctiveness of species \eqn{j} can be defined as the number of sites where it occurs (\eqn{n_j}), or the sum of its relative frequencies (\eqn{p_j}). Relative frequencies are computed sitewise and \eqn{sum_j{p_ij}}s at site \eqn{i} sum up to \eqn{1}.
+
+The contribution of site \eqn{i} to the total diversity is given by \eqn{alpha_i = sum_j(1 / n_ij)} when dealing with richness and \eqn{alpha_i = sum(p_ij * (1 - p_ij))} for the Simpson index.
+
+The unit distinctiveness of site \eqn{i} is the average of the species distinctiveness, averaging only those species which occur at site \eqn{i}. For species richness: \eqn{alpha_i = mean(n_i)} (in the paper, the second equation contains a typo, \eqn{n} is without index). For the Simpson index: \eqn{alpha_i = mean(n_i)}.
+
+The Lu et al. (2007) gives an in-depth description of the different indices.
+}
+\value{
+An object of class 'contribdiv'.
+}
+\references{
+Lu, H. P., Wagner, H. H. and Chen, X. Y. 2007. A contribution diversity approach to evaluate species diversity.
+\emph{Basic and Applied Ecology}, 8, 1--12.
+}
+\author{\enc{P\'eter S\'olymos}{Peter Solymos}, \email{solymos at ualberta.ca}}
+\seealso{\code{\link{adipart}}, \code{\link{diversity}}}
+\examples{
+## Artificial example given in
+## Table 2 in Lu et al. 2007
+x <- matrix(c(
+1/3,1/3,1/3,0,0,0,
+0,0,1/3,1/3,1/3,0,
+0,0,0,1/3,1/3,1/3),
+3, 6, byrow = TRUE,
+dimnames = list(LETTERS[1:3],letters[1:6]))
+x
+## Compare results with Table 2
+contribdiv(x, "richness")
+contribdiv(x, "simpson")
+contribdiv(x, "richness", relative = TRUE, scaled = FALSE)
+contribdiv(x, "simpson", relative = TRUE, scaled = FALSE)
+## BCI data set
+data(BCI)
+opar <- par(mfrow=c(2,2))
+plot(contribdiv(BCI, "richness"), main = "Absolute")
+plot(contribdiv(BCI, "richness", relative = TRUE), main = "Relative")
+plot(contribdiv(BCI, "simpson"))
+plot(contribdiv(BCI, "simpson", relative = TRUE))
+par(opar)
+}
+\keyword{multivariate}
More information about the Vegan-commits
mailing list