[Vegan-commits] r1516 - in branches/1.17: inst man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Mon Feb 28 16:53:47 CET 2011
Author: jarioksa
Date: 2011-02-28 16:53:47 +0100 (Mon, 28 Feb 2011)
New Revision: 1516
Modified:
branches/1.17/inst/ChangeLog
branches/1.17/man/beals.Rd
branches/1.17/man/plot.cca.Rd
branches/1.17/man/scores.Rd
branches/1.17/man/vegdist.Rd
Log:
merge r1510:1515 - Rd fixes and updates
Modified: branches/1.17/inst/ChangeLog
===================================================================
--- branches/1.17/inst/ChangeLog 2011-02-28 15:48:41 UTC (rev 1515)
+++ branches/1.17/inst/ChangeLog 2011-02-28 15:53:47 UTC (rev 1516)
@@ -14,6 +14,9 @@
* merged r1500,4: decorana zero-eigenvalue fix.
+ * merged r1510 thru 1515: documentation fixes in beals.Rd,
+ plot.cca.Rd, scores.Rd, and vegdist.Rd.
+
Version 1.17-7 (released February 16, 2011)
* merged r1489: nestednodf with weighted = FALSE.
Modified: branches/1.17/man/beals.Rd
===================================================================
--- branches/1.17/man/beals.Rd 2011-02-28 15:48:41 UTC (rev 1515)
+++ branches/1.17/man/beals.Rd 2011-02-28 15:53:47 UTC (rev 1516)
@@ -6,9 +6,9 @@
\title{Beals Smoothing and Degree of Absence}
\description{
Beals smoothing replaces each entry in the community data with a
- probability of target species occurring in that particular site, based
- on the joint occurrences of target species with the species that
- actually occur in the site. Swan's (1970) degree of absence applies
+ probability of a target species occurring in that particular site, based
+ on the joint occurrences of the target species with the species that
+ actually occur in the site. Swan's (1970) degree of absence applies
Beals smoothing to zero items so long that all zeros are replaced
with smoothed values.
}
@@ -23,8 +23,8 @@
\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}{Numeric. For function \code{beals} it specifies if and how abundance
- values have to be used. See details for more explanation.}
+ \item{type}{Numeric. Specifies if and how abundance values have to be
+ used in function \code{beals}. See details for more explanation.}
\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},
@@ -34,17 +34,17 @@
\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}
+ species \eqn{j} occurs at 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
+ species at 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 occurrences 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}
function can be interpreted as a mean of conditioned probabilities (De
- \enc{Cáceres}{Caceres} & Legendre 2008). The current function is
+ \enc{Cáceres}{Caceres} & Legendre 2008). The present function is
generalized to abundance values (De \enc{Cáceres}{Caceres} & Legendre
2008).
@@ -52,23 +52,23 @@
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
+ used to compute weighted averages of conditioned
probabilities. \code{type = 3} abundances are used to compute both
- conditioned probabilities and the weighted average.
+ conditioned probabilities and weighted averages.
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
- does not maintain the information on species presences: A species may
- have a higher probability of occurrence in a site where it does not
- occur than in sites where it occurs. Moreover, it regularizes data
- too strongly. The method may be useful in identifying species that
+ does not maintain the information on species presences: a species may
+ have a higher probability of occurrence at a site where it does not
+ occur than at sites where it occurs. Moreover, it regularizes data
+ too strongly. The method may be useful in identifying species that
belong to the species pool (Ewald 2002) or to identify suitable
unoccupied patches in metapopulation analysis
(\enc{Münzbergová}{Munzbergova} & Herben
- 2004). In this case, the function should 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.
+ 2004). In this case, the function should be called with \code{include
+ = FALSE} for cross-validation smoothing for species; argument
+ \code{species} can be used if only one species is studied.
Swan (1970) suggested replacing zero values with degrees of absence of
a species in a community data matrix. Swan expressed the method in
@@ -80,14 +80,15 @@
\code{\link{stepacross}}), but very rarely used.
}
\value{
- The function returns a transformed data matrix or a vector in case of
- asking Beals smoothing for a single species.
+ The function returns a transformed data matrix or a vector if Beals smoothing
+ is requested 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.
+Beals, E.W. 1984. Bray-Curtis ordination: an effective strategy for
+analysis of multivariate ecological data. Pp. 1--55 in: MacFadyen, A. &
+E.D. Ford [eds.] \emph{Advances in Ecological Research, 14}. Academic
+Press, London.
De \enc{Cáceres}{Caceres}, M. & Legendre, P. 2008. Beals smoothing
revisited. \emph{Oecologia} 156: 657--669.
@@ -103,8 +104,8 @@
habitats in metapopulation studies using co-occurrence of species. \emph{Oikos}
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.
+Swan, J.M.A. 1970. An examination of some ordination problems by use of
+simulated vegetational data. \emph{Ecology} 51: 89--102.
}
\author{Miquel De \enc{Cáceres}{Caceres} and Jari Oksanen}
Modified: branches/1.17/man/plot.cca.Rd
===================================================================
--- branches/1.17/man/plot.cca.Rd 2011-02-28 15:48:41 UTC (rev 1515)
+++ branches/1.17/man/plot.cca.Rd 2011-02-28 15:53:47 UTC (rev 1516)
@@ -37,7 +37,7 @@
\arguments{
\item{x, object}{A \code{cca} result object.}
\item{choices}{Axes shown.}
- \item{display}{Scores shown. These must some of the alternatives
+ \item{display}{Scores shown. These must include some of the alternatives
\code{species} or \code{sp} for species scores, \code{sites} or
\code{wa} for site scores, \code{lc} for linear constraints or ``LC
scores'', or \code{bp} for biplot arrows or \code{cn} for centroids
Modified: branches/1.17/man/scores.Rd
===================================================================
--- branches/1.17/man/scores.Rd 2011-02-28 15:48:41 UTC (rev 1515)
+++ branches/1.17/man/scores.Rd 2011-02-28 15:53:47 UTC (rev 1516)
@@ -14,39 +14,57 @@
\arguments{
\item{x}{ An ordination result. }
- \item{choices}{ Ordination axes. If missing, returns all axes.}
+ \item{choices}{ Ordination axes. If missing, default method returns all axes.}
\item{display}{ Partial match to access scores for \code{sites} or
\code{species}.}
\item{...}{ Other parameters (unused). }
}
\details{
- Functions \code{\link{cca}} and \code{\link{decorana}} have specific
- \code{scores} function to access their ordination scores. Most
- standard ordination methods of libraries \pkg{mva}, \pkg{multiv} and
- \pkg{MASS} do not have a specific \code{class}, and no specific method can be
- written for them. However, \code{scores.default} guesses where
- some commonly used functions keep their site scores and possible
- species scores. For site scores, the function seeks items in order
- \code{points}, \code{rproj}, \code{x}, and \code{scores}. For species,
- the seeking order is \code{cproj}, \code{rotation}, and
- \code{loadings}.
+ Function \code{scores} is a generic method in \pkg{vegan}. Several
+ \pkg{vegan} functions have their own \code{scores} methods with their
+ own defaults and with some new arguments. This help page describes
+ only the default method. For other methods, see, e.g.,
+ \code{\link{scores.cca}}, \code{\link{scores.rda}},
+ \code{\link{scores.decorana}}.
+
+ All \pkg{vegan} ordination functions should have a \code{scores}
+ method which should be used to extract the scores instead of
+ directly accessing them. Scaling and transformation of scores should
+ also happen in the \code{scores} function. If the \code{scores}
+ function is available, the results can be plotted using
+ \code{\link{ordiplot}}, \code{\link{ordixyplot}} etc., and the
+ ordination results can be compared in \code{\link{procrustes}}
+ analysis.
+
+ The \code{scores.default} function is used to extract scores from
+ non-\pkg{vegan} ordination results. Most standard ordination
+ methods of libraries \pkg{mva}, \pkg{multiv} and \pkg{MASS} do not
+ have a specific \code{class}, and no specific method can be written
+ for them. However, \code{scores.default} guesses where some
+ commonly used functions keep their site scores and possible species
+ scores.
+
If \code{x} is a matrix, \code{scores.default} returns the chosen
columns of that matrix, ignoring whether species or sites were
requested (do not regard this as a bug but as a feature, please).
Currently the function seems to work at least for \code{\link[MASS]{isoMDS}},
- \code{\link{prcomp}}, \code{\link{princomp}}. It may work in
- other cases or fail mysteriously.
+ \code{\link{prcomp}}, \code{\link{princomp}} and some \pkg{ade4} objects.
+ It may work in other cases or fail mysteriously.
}
\value{
- The function returns a matrix of requested scores.
+ The function returns a matrix of scores.
}
\author{Jari Oksanen }
-\seealso{\code{\link{scores.cca}}, \code{\link{scores.decorana}}. These
-have somewhat different interface -- \code{\link{scores.cca}} in
-particular -- but all work with keywords \code{display="sites"} and
-\code{display="species"} and return a matrix with these.
+\seealso{
+ \code{\link{scores.cca}}, \code{\link{scores.decorana}}. These have
+ somewhat different interface -- \code{\link{scores.cca}} in
+ particular -- but all work with keywords \code{display="sites"} and
+ return a matrix. However, they may also return a list of matrices,
+ and some other \code{scores} methods will have quite different
+ arguments.
}
+
\examples{
data(varespec)
vare.pca <- prcomp(varespec)
Modified: branches/1.17/man/vegdist.Rd
===================================================================
--- branches/1.17/man/vegdist.Rd 2011-02-28 15:48:41 UTC (rev 1515)
+++ branches/1.17/man/vegdist.Rd 2011-02-28 15:53:47 UTC (rev 1516)
@@ -166,18 +166,22 @@
below one, and two identical communities may have dissimilarity
slightly above zero.
- Chao index tries to take into account the number of unseen species
- pairs, similarly as Chao's method in \code{\link{specpool}}. Function
- \code{vegdist} implements a Jaccard type index defined as \eqn{d_{jk}
- = U_j U_k/(U_j + U_k - U_j U_k)}{d[jk] = U[j]*U[k]/(U[j] + U[k] -
- U[j]*U[k])}, where \eqn{U_j = C_j/N_j + (N_k - 1)/N_k \times a_1/(2
- a_2) \times S_j/N_j}{U[j] = C[j]/N[j] + (N[k] -1)/N[k] * a1/(2*a2) *
- S[j]/N[j]}. Here \eqn{C_j}{C[j]} is the total number of individuals in
- species shared with site \eqn{k}, \eqn{N} is the total number of
- individuals, \eqn{a_1}{a1} and \eqn{a_2}{a2} are number of species
- occurring only with one or two individuals in another site, and
- \eqn{S_j}{S[j]} is the number of individuals in species that occur
- only with one individual in another site (Chao et al. 2005).
+ Chao index tries to take into account the number of unseen species
+ pairs, similarly as in \code{method = "chao"} in
+ \code{\link{specpool}}. Function \code{vegdist} implements a Jaccard
+ type index defined as \eqn{d_{jk} = 1 - U_j U_k/(U_j + U_k - U_j
+ U_k)}{d[jk] = 1 - U[j]*U[k]/(U[j] + U[k] - U[j]*U[k])}, where
+ \eqn{U_j = C_j/N_j + (N_k - 1)/N_k \times a_1/(2 a_2) \times
+ S_j/N_j}{U[j] = C[j]/N[j] + (N[k] -1)/N[k] * a1/(2*a2) * S[j]/N[j]},
+ and similarly for \eqn{U_k}{U[k]}. Here \eqn{C_j}{C[j]} is the total
+ number of individuals in the species of site \eqn{j} that are shared
+ with site \eqn{k}, \eqn{N_j}{N[j]} is the total number of
+ individuals at site \eqn{j}, \eqn{a_1}{a1} (and \eqn{a_2}{a2}) are
+ the number of species occurring in site \eqn{j} that have only one
+ (or two) individuals in site \eqn{k}, and \eqn{S_j}{S[j]} is the
+ total number of individuals in the species present at site \eqn{j}
+ that occur with only one individual in site \eqn{k} (Chao et
+ al. 2005).
Morisita index can be used with genuine count data (integers) only. Its
Horn--Morisita variant is able to handle any abundance data.
More information about the Vegan-commits
mailing list