[Vegan-commits] r529 - in pkg: R inst man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Mon Oct 20 07:17:59 CEST 2008
Author: jarioksa
Date: 2008-10-20 07:17:59 +0200 (Mon, 20 Oct 2008)
New Revision: 529
Modified:
pkg/R/beals.R
pkg/inst/ChangeLog
pkg/man/beals.Rd
Log:
beals.R replaced with new code by Miquel de Caceres implementing new options and methods (see De Caceres & Legendre, Oecologia 156, 657-669; 2008)
Modified: pkg/R/beals.R
===================================================================
--- pkg/R/beals.R 2008-10-18 02:09:44 UTC (rev 528)
+++ pkg/R/beals.R 2008-10-20 05:17:59 UTC (rev 529)
@@ -1,15 +1,90 @@
-"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, x, mode=0,incSp=TRUE)' #
+## #
+## x matrix to be replaced by beals values #
+## refX matrix to be used as source for joint occurrences #
+## incSp flag to include target species in the computation #
+## mode sets the way to use abundance values #
+## 0 - presence/absence #
+## 1 - abundances for conditioned probabilities #
+## 2 - abundances for weighted average #
+## 3 - abundances for both #
+##############################################################
+
+beals <- function(x, refX = x, mode=0, incSp = TRUE)
{
+ if(is.null(refX))
+ refX <- x
+ refX <- as.matrix(refX)
x <- as.matrix(x)
- x <- ifelse(x > 0, 1, 0)
+
+ 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
+ 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
+ }
+
+ ## Average of conditioned probabilities
S <- rowSums(x)
- M <- crossprod(x)
- M <- sweep(M, 2, diag(M), "/")
+ b <-x
for (i in 1:nrow(x)) {
- x[i,] <- rowSums(sweep(M, 2, x[i,], "*"))
+ b[i, ] <- rowSums(sweep(M, 2, x[i, ], "*"))
}
- x <- sweep(x, 1, S, "/")
- x
+
+ SM <- rep(S,ncol(x))
+ if(!incSp)
+ SM <- SM - x
+ b <- b/replace(SM,SM==0,1)
+ b
}
+
+##############################################################
+## COMPUTES BEALS SMOOTHING FOR A GIVEN SPECIES #
+## #
+## x matrix to be replaced by beals values #
+## refX matrix to be used as source for joint occurrences #
+## incSp flag to include species in the computation #
+## mode sets the way to use abundance values #
+## 0 - presence/absence #
+## 1 - abundances for conditioned probabilities #
+## 2 - abundances for weighted average #
+## 3 - abundances for both #
+##############################################################
+
+beals.sp <- function(x, spIndex, refX = x, mode=0, incSp = FALSE)
+{
+ if(is.null(refX))
+ refX <- x
+ refX <- as.matrix(refX)
+
+ 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
+ C <- colSums(refX)
+ M <- crossprod(refX,ifelse(refX > 0, 1, 0)[,spIndex])
+ M <- M/replace(C,C==0,1)
+ if(!incSp)
+ M[spIndex]<-0
+
+ ## Average of conditioned probabilities
+ b <- rowSums(sweep(x,2,M,"*"))
+ S <- rowSums(x)
+
+ if (!incSp)
+ S <- S - x[,spIndex]
+ b <- b/replace(S,S==0,1)
+ b
+}
Modified: pkg/inst/ChangeLog
===================================================================
--- pkg/inst/ChangeLog 2008-10-18 02:09:44 UTC (rev 528)
+++ pkg/inst/ChangeLog 2008-10-20 05:17:59 UTC (rev 529)
@@ -4,10 +4,18 @@
Version 1.16-2 (opened October 10, 2008)
- * permatfull: bug of row/col marins is fixed, shuffle argument is
- added to enable individual and sample based randomisation of
- count data (or both) when not all the margins are fixed.
+ * beals: replaced old beals.R with the new code by Miquel de
+ Caceres with new methods described in De Caceres & Legendre
+ (Oecologia 156, 657-669; 2008). This also implements the
+ cross-validatory Beals of Munzbergova & Herben (Oikos 104,
+ 408-414; 2004) plus many new options of unbiasing estimates. In
+ addition to new beals, there is a function for bealsing only one
+ target species.
+ * permatfull: bug of row/col marins is fixed, shuffle argument is
+ added to enable individual and sample based randomisation of count
+ data (or both) when not all the margins are fixed.
+
* anosim: API and documentation made similar to mrpp to combine
their documentation. Now anosim can take data frame input and find
the dissimilarities internally.
Modified: pkg/man/beals.Rd
===================================================================
--- pkg/man/beals.Rd 2008-10-18 02:09:44 UTC (rev 528)
+++ pkg/man/beals.Rd 2008-10-20 05:17:59 UTC (rev 529)
@@ -1,6 +1,7 @@
\encoding{UTF-8}
\name{beals}
\alias{beals}
+\alias{beals.sp}
\alias{swan}
\title{Beals Smoothing and Degree of Absence }
@@ -13,11 +14,29 @@
with smoothed values.
}
\usage{
-beals(x)
+beals(x, refX = x, mode = 0, incSp = TRUE)
+beals.sp(x, spIndex, refX = x, mode = 0, incSp = FALSE)
swan(x)
}
\arguments{
\item{x}{Community data frame or matrix }
+ \item{spIndex}{Index of the single species whose Beals smoothing
+ values are to be computed. }
+ \item{refX}{ Community data frame or matrix to be used to compute
+ joint occurrences. If \code{refX=NULL} then \code{x} is used to
+ compute the joint occurrences.}
+ \item{incSp}{ This 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{incSp=TRUE},
+ while the formulation of Münzbergová and Herben is equal to
+ \code{incSp=FALSE}. }
+ \item{mode }{Specifies if and how abundance values have to be
+ used. \code{mode = 0} presence/absence mode. \code{mode = 1}
+ abundances in \code{refX} (or \code{x}) are used to compute
+ conditioned probabilities. \code{mode = 2} abundances in \code{x} are
+ used to compute weighted average of conditioned
+ probabilities. \code{mode = 3} abundances are used to compute both
+ conditioned probabilities and the weighted average.}
}
\details{
Beals smoothing is the estimated probability \eqn{p_{ij}}{p[ij]}
@@ -28,7 +47,12 @@
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).
+ 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 Caceres & Legendre 2008). The
+ currrent function is generalized to abundance values (De Caceres &
+ Legendre 2008).
Beals smoothing was originally suggested as a method of data
transformation to remove excessive zeros (Beals 1984, McCune
@@ -40,7 +64,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{incSp
+ = FALSE} for cross-validatory smoothing for species, and function
+ \code{beals.sp} can be used if onl 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
@@ -57,39 +83,47 @@
\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 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 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, incSp = 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, mode =3, incSp = FALSE)
+## Uses abundance information.
+## Vector with beals smoothing values corresponding to the first species
+## in dune.
+beals.sp(dune, spIndex=1, incSp=TRUE)
}
\keyword{ manip }
\keyword{ smooth }
More information about the Vegan-commits
mailing list