[Vegan-commits] r771 - in branches/1.15: R inst man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Mon Mar 30 20:29:17 CEST 2009
Author: jarioksa
Date: 2009-03-30 20:29:17 +0200 (Mon, 30 Mar 2009)
New Revision: 771
Modified:
branches/1.15/R/beals.R
branches/1.15/inst/ChangeLog
branches/1.15/man/beals.Rd
Log:
Miquel de Caceres's new beals code merged to branches/1.15
Modified: branches/1.15/R/beals.R
===================================================================
--- branches/1.15/R/beals.R 2009-03-30 16:42:02 UTC (rev 770)
+++ branches/1.15/R/beals.R 2009-03-30 18:29:17 UTC (rev 771)
@@ -1,15 +1,67 @@
-"beals" <-
- function(x)
+##############################################################
+## COMPUTES BEALS SMOOTHING FOR ALL SPECIES IN TABLE #
+## This is a more complete function than the previous one #
+## in the vegan package. The parameter values that give the #
+## equivalence are 'beals(x, NA, x, 0, include=TRUE)' #
+## #
+## 'x' matrix to be replaced by beals values #
+## 'reference' matrix to be used as source for joint occurrences#
+## 'type' sets the way to use abundance values #
+## 0 - presence/absence #
+## 1 - abundances for conditioned probabilities #
+## 2 - abundances for weighted average #
+## 3 - abundances for both #
+## 'species' a column index used to compute Beals function #
+## for a single species. The default (NA) indicates #
+## all species. #
+## 'include' flag to include target species in the computation#
+##############################################################
+beals<-function(x, species=NA, reference=x, type=0, include=TRUE)
{
- x <- as.matrix(x)
- x <- ifelse(x > 0, 1, 0)
- S <- rowSums(x)
- M <- crossprod(x)
- M <- sweep(M, 2, diag(M), "/")
- for (i in 1:nrow(x)) {
- x[i,] <- rowSums(sweep(M, 2, x[i,], "*"))
+ refX <- reference
+ # this checks whether it was chosen from available options
+ mode <- as.numeric(match.arg(as.character(type), c("0","1","2","3")))
+ spIndex <- species
+ incSp <- include
+# if(is.null(refX)) # I think this is unnecessary because of the default above
+# refX<-x # and it should look like missing(refX) and not is.null(refX)
+ refX <- as.matrix(refX)
+ x <- as.matrix(x)
+ if(mode==0 || mode ==2) refX <- ifelse(refX > 0, 1, 0)
+ if(mode==0 || mode ==1) x <- ifelse(x > 0, 1, 0)
+ #Computes conditioned probabilities
+ if(is.na(spIndex)){
+ M <- crossprod(ifelse(refX > 0, 1, 0),refX)
+ C <-diag(M)
+ M <- sweep(M, 2, replace(C,C==0,1), "/")
+ if(!incSp)
+ for (i in 1:ncol(refX))
+ M[i,i]<-0
+ } else {
+ C<-colSums(refX)
+ M<-crossprod(refX,ifelse(refX > 0, 1, 0)[,spIndex])
+ M<-M/replace(C,C==0,1)
+ if(!incSp)
+ M[spIndex]<-0
}
- x <- sweep(x, 1, S, "/")
- x
+ #Average of conditioned probabilities
+ S <- rowSums(x)
+ if(is.na(spIndex)) {
+ b <-x
+ for (i in 1:nrow(x)) {
+ b[i, ] <- rowSums(sweep(M, 2, x[i, ], "*"))
+ }
+ SM<-rep(S,ncol(x))
+ if(!incSp)
+ SM<-SM-x
+ b <- b/replace(SM,SM==0,1)
+ } else {
+ b<-rowSums(sweep(x,2,M,"*"))
+ if(!incSp)
+ S<-S-x[,spIndex]
+ b <- b/replace(S,S==0,1)
+ }
+# attr(b, "smoothtype") <- mode
+# class(b) <- c("beals", class(b)) # this can later be used to write the methods, i.e. beals test, etc.
+ return(b)
}
-
Modified: branches/1.15/inst/ChangeLog
===================================================================
--- branches/1.15/inst/ChangeLog 2009-03-30 16:42:02 UTC (rev 770)
+++ branches/1.15/inst/ChangeLog 2009-03-30 18:29:17 UTC (rev 771)
@@ -5,6 +5,8 @@
Version 1.15-2 (opened January 14, 2009)
+ * merged new beals code by Miquel de Caceres (rev 528:531).
+
* copied dispindmorisita at rev769 from pkg/vegan.
* copied kendall.global at rev767 from pkg/vegan.
Modified: branches/1.15/man/beals.Rd
===================================================================
--- branches/1.15/man/beals.Rd 2009-03-30 16:42:02 UTC (rev 770)
+++ branches/1.15/man/beals.Rd 2009-03-30 18:29:17 UTC (rev 771)
@@ -13,23 +13,45 @@
with smoothed values.
}
\usage{
-beals(x)
+beals(x, species = NA, reference = x, type = 0, include = TRUE)
swan(x)
}
\arguments{
\item{x}{Community data frame or matrix }
+ \item{species}{ Column index used to compute Beals function for a single species. The default (\code{NA}) indicates that the function will be computed for all species.}
+ \item{reference}{ Community data frame or matrix to be used to compute
+ joint occurrences. By default, \code{x} is used as reference to
+ compute the joint occurrences.}
+ \item{type}{Specifies if and how abundance values have to be
+ used. \code{type = 0} presence/absence mode. \code{type = 1}
+ abundances in \code{reference} (or \code{x}) are used to compute
+ conditioned probabilities. \code{type = 2} abundances in \code{x} are
+ used to compute weighted average of conditioned
+ probabilities. \code{type = 3} abundances are used to compute both
+ conditioned probabilities and the weighted average.}
+ \item{include}{This logical flag indicates whether the target species has to be
+ included when computing the mean of the conditioned probabilities. The
+ original Beals (1984) definition is equivalent to \code{include=TRUE},
+ while the formulation of \enc{Münzbergová}{Munzbergova} and Herben is
+ equal to \code{include=FALSE}. }
}
\details{
- Beals smoothing is the estimated probability \eqn{p_{ij}}{p[ij]}
- that species \eqn{j} occurs in site \eqn{i}. It is defined as
- \eqn{p_{ij} = \frac{1}{S_i} \sum_k \frac{N_{jk} I_{ik}}{N_k}}{p[ij]
- = 1/S[i] Sum(k) N[jk] I[ik] / N[k]}, where \eqn{S_i}{S[i]} is the
- number of species on site \eqn{i}, \eqn{N_{jk}}{N[jk]} is the number of
- joint occurrences of species \eqn{j} and \eqn{k},
- \eqn{N_k}{N[k]} is the number of occurences of species \eqn{k}, and
- \eqn{I} is the incidence (0 or 1) of species (this last term is
- usually omitted from the equation, but it is necessary).
+ Beals smoothing is the estimated probability \eqn{p_{ij}}{p[ij]} that
+ species \eqn{j} occurs in site \eqn{i}. It is defined as \eqn{p_{ij}
+ = \frac{1}{S_i} \sum_k \frac{N_{jk} I_{ik}}{N_k}}{p[ij] = 1/S[i]
+ Sum(k) N[jk] I[ik] / N[k]}, where \eqn{S_i}{S[i]} is the number of
+ species on site \eqn{i}, \eqn{N_{jk}}{N[jk]} is the number of joint
+ occurrences of species \eqn{j} and \eqn{k}, \eqn{N_k}{N[k]} is the
+ number of occurences of species \eqn{k}, and \eqn{I} is the incidence
+ (0 or 1) of species (this last term is usually omitted from the
+ equation, but it is necessary). As \eqn{N_{jk}}{N[jk]} can be
+ interpreted as a mean of conditional probability, the \code{beals}
+ fucntion can be interpred as a mean of conditioned probabilities (De
+ \enc{Cáceres}{Caceres} & Legendre 2008). The currrent function is
+ generalized to abundance values (De \enc{Cáceres}{Caceres} & Legendre
+ 2008).
+
Beals smoothing was originally suggested as a method of data
transformation to remove excessive zeros (Beals 1984, McCune
1994). However, it is not a suitable method for this purpose since it
@@ -40,7 +62,9 @@
belong to the species pool (Ewald 2002) or to identify suitable
unoccupied patches in metapopulation analysis
(\enc{Münzbergová}{Munzbergova} & Herben
- 2004). The function is provided here for the brave.
+ 2004). In this case, the function shold be called with \code{include
+ = FALSE} for cross-validatory smoothing for species, and argument
+ \code{species} can be used if only one species was studied.
Swan (1970) suggested replacing zero values with degrees of absence of
a species in a community data matrix. Swan expressed the method in
@@ -52,44 +76,52 @@
\code{\link{stepacross}}), but very rarely used.
}
\value{
- The function returns a transformed data matrix.
+ The function returns a transformed data matrix or a vector in case of asking Beals smoothing for a single species.
}
\references{
Beals, E.W. 1984. Bray-Curtis-ordination: an effective strategy for
-analysis of multivariate ecological data. \emph{Adv. Ecol. Res.} 14: 1-55.
+analysis of multivariate ecological data. \emph{Adv. Ecol. Res.} 14:
+1--55.
+
+De \enc{Cáceres}{Caceres}, M. & Legendre, P. 2008. Beals smoothing
+revisited. \emph{Oecologia} 156: 657--669.
Ewald, J. 2002. A probabilistic approach to estimating species pools
-from large compositional matrices. \emph{J. Veg. Sci.} 13: 191-198.
+from large compositional matrices. \emph{J. Veg. Sci.} 13: 191--198.
McCune, B. 1994. Improving community ordination with the Beals smoothing
-function. \emph{Ecoscience} 1: 82-86.
+function. \emph{Ecoscience} 1: 82--86.
\enc{Münzbergová}{Munzbergova}, Z. & Herben, T. 2004. Identification of
suitable unoccupied
habitats in metapopulation studies using co-occurrence of species. \emph{Oikos}
-105: 408-414.
+105: 408--414.
Swan, J.M.A. (1970) An examination of some ordination problems by use of
simulated vegetational data. \emph{Ecology} 51, 89--102.
}
-\author{Jari Oksanen}
-\note{
- The current function is modelled as closely as possible after Beals
- (1984) and McCune (1994). It seems that
- \enc{Münzbergová}{Munzbergova} and Herben (2004)
- use slightly different formulation.
-}
+\author{Miquel De \enc{Cáceres}{Caceres} and Jari Oksanen}
+
\seealso{\code{\link{decostand}} for proper standardization methods,
\code{\link{specpool}} for an attempt to assess the size of species
pool. }
\examples{
data(dune)
+## Default
x <- beals(dune)
+## Remove target species
+x <- beals(dune, include = FALSE)
## Smoothed values against presence or absence of species
pa <- decostand(dune, "pa")
boxplot(as.vector(x) ~ unlist(pa), xlab="Presence", ylab="Beals")
+## Remove the bias of tarbet species: Yields lower values.
+beals(dune, type =3, include = FALSE)
+## Uses abundance information.
+## Vector with beals smoothing values corresponding to the first species
+## in dune.
+beals(dune, species=1, include=TRUE)
}
\keyword{ manip }
\keyword{ smooth }
More information about the Vegan-commits
mailing list