[Vegan-commits] r218 - branches/1.11-0/man

noreply at r-forge.r-project.org noreply at r-forge.r-project.org
Sat Feb 16 17:19:46 CET 2008


Author: gsimpson
Date: 2008-02-16 17:19:46 +0100 (Sat, 16 Feb 2008)
New Revision: 218

Modified:
   branches/1.11-0/man/CCorA.Rd
   branches/1.11-0/man/cca.Rd
   branches/1.11-0/man/cca.object.Rd
   branches/1.11-0/man/decorana.Rd
   branches/1.11-0/man/decostand.Rd
Log:
Documentation updates and tidying

Modified: branches/1.11-0/man/CCorA.Rd
===================================================================
--- branches/1.11-0/man/CCorA.Rd	2008-02-16 14:16:33 UTC (rev 217)
+++ branches/1.11-0/man/CCorA.Rd	2008-02-16 16:19:46 UTC (rev 218)
@@ -2,6 +2,7 @@
 \alias{CCorA}
 \alias{print.CCorA}
 \alias{biplot.CCorA}
+\concept{ordination}
 
 \title{Canonical Correlation Analysis}
 
@@ -11,50 +12,57 @@
 
 \usage{
 CCorA(Y, X, stand.Y=FALSE, stand.X=FALSE, nperm = 0, ...)
+
 \method{biplot}{CCorA}(x, xlabs, which = 1:2, ...)
 }
 
 \arguments{
-\item{Y}{ left matrix }
-\item{X}{ right matrix }
-\item{stand.Y}{ Y will be standardized if \code{TRUE} }
-\item{stand.X}{ X1 will be standardized if \code{TRUE} }
-\item{nperm}{Number of permutations to evaluate the significance of
-  Pillai's trace}
-\item{x}{\code{CCoaR} result object}
-\item{xlabs}{Row labels. The default is to use row names, \code{NULL}
-  uses row numbers instead, and \code{NA} suppresses plotting row names
-  completely}
-\item{which}{ \code{1} plots \code{Y} reseults, and
-  \code{2} plots \code{X1} results }
-\item{\dots}{Other parameters passed to functions. \code{biplot.CCorA} passes
-  graphical parameters to \code{\link{biplot}} and
-  \code{\link{biplot.default}}, \code{CCorA} currently ignores extra parameters.}
+  \item{Y}{ left matrix. }
+  \item{X}{ right matrix. }
+  \item{stand.Y}{ logical; should \code{Y} be standardized? }
+  \item{stand.X}{ logical; should \code{X} be standardized? }
+  \item{nperm}{ numeric; Number of permutations to evaluate the
+    significance of Pillai's trace}
+  \item{x}{\code{CCoaR} result object}
+  \item{xlabs}{Row labels. The default is to use row names, \code{NULL}
+    uses row numbers instead, and \code{NA} suppresses plotting row names
+    completely}
+  \item{which}{ \code{1} plots \code{Y} reseults, and
+    \code{2} plots \code{X1} results }
+  \item{\dots}{Other arguments passed to functions. \code{biplot.CCorA}
+    passes graphical arguments to \code{\link{biplot}} and
+    \code{\link{biplot.default}}, \code{CCorA} currently ignores extra 
+    arguments.} 
 }
 
-\details{ Canonical correlation analysis (Hotelling 1936) seeks linear
-combinations of the variables of Y that are maximally correlated to
-linear combinations of the variables of X. The analysis estimates the
-relationships and displays them in graphs.
+\details{
+  Canonical correlation analysis (Hotelling 1936) seeks linear
+  combinations of the variables of \code{Y} that are maximally
+  correlated to linear combinations of the variables of \code{X}. The
+  analysis estimates the relationships and displays them in graphs.
 
-Algorithmic notes:
-\enumerate{
-  \item
-  All data matrices are replaced by their PCA object scores, computed by SVD.
-  \item
-  The blunt approach would be to read the three matrices, compute the
-  covariance matrices, then the matrix
-  \code{S12 \%*\% inv(S22) \%*\% t(S12) \%*\% inv(S11)}.
+  Algorithmic notes:
+  \enumerate{
+    \item
+    All data matrices are replaced by their PCA object scores, computed
+    by SVD.
+    \item
+    The blunt approach would be to read the three matrices, compute the
+    covariance matrices, then the matrix
+    \code{S12 \%*\% inv(S22) \%*\% t(S12) \%*\% inv(S11)}.
     Its trace is Pillai's trace statistic. 
-  \item
-  This approach may fail, however, when there is heavy multicollinearity in very sparse data matrices, as it is the case in 4th-corner inflated data matrices for example. The safe approach is to replace all data matrices by their PCA object scores.
-  \item
-  Inversion by \code{\link{solve}} is avoided. Computation of inverses
-  is done by SVD  (\code{\link{svd}})in most cases.
-  \item
-  Regression by OLS is also avoided. Regression residuals are
-  computed by QR decomposition (\code{\link{qr}}).
-}
+    \item
+    This approach may fail, however, when there is heavy multicollinearity
+    in very sparse data matrices, as it is the case in 4th-corner inflated
+    data matrices for example. The safe approach is to replace all data
+    matrices by their PCA object scores.
+    \item
+    Inversion by \code{\link{solve}} is avoided. Computation of inverses
+    is done by \acronym{SVD}  (\code{\link{svd}}) in most cases.
+    \item
+    Regression by \acronym{OLS} is also avoided. Regression residuals are
+    computed by \acronym{QR} decomposition (\code{\link{qr}}).
+  }
 
 The \code{biplot} function can produce two biplots, each for the left
 matrix and right matrix solutions. The function passes all arguments to
@@ -63,17 +71,22 @@
 }
 
 \value{
-Function \pkg{CCorA} returns a list containing the following results and matrices:
-\item{ Pillai }{ Pillai's trace statistic = sum of canonical eigenvalues. }
-\item{ EigenValues }{ Canonical eigenvalues. They are the squares of the canonical correlations. }
-\item{ CanCorr }{ Canonical correlations. }
-\item{ Mat.ranks }{ Ranks of matrices Y and X1 (possibly after controlling for X2). }
-\item{ RDA.Rsquares }{ Bimultivariate redundancy coefficients (R-squares) of RDAs of Y|X1 and X1|Y. }
-\item{ RDA.adj.Rsq }{ RDA.Rsquares adjusted for n and number of explanatory variables. }
-\item{ AA }{ Scores of Y variables in Y biplot. }
-\item{ BB }{ Scores of X1 variables in X1 biplot. }
-\item{ Cy }{ Object scores in Y biplot. }
-\item{ Cx }{ Object scores in X1 biplot. }
+  Function \code{CCorA} returns a list containing the following components:
+  \item{ Pillai }{ Pillai's trace statistic = sum of canonical
+    eigenvalues. } 
+  \item{ EigenValues }{ Canonical eigenvalues. They are the squares of the
+    canonical correlations. }
+  \item{ CanCorr }{ Canonical correlations. }
+  \item{ Mat.ranks }{ Ranks of matrices \code{Y} and X1 (possibly after
+    controlling for X2). }
+  \item{ RDA.Rsquares }{ Bimultivariate redundancy coefficients
+    (R-squares) of RDAs of Y|X1 and X1|Y. } 
+  \item{ RDA.adj.Rsq }{ \code{RDA.Rsquares} adjusted for n and number of
+    explanatory variables. }
+  \item{ AA }{ Scores of Y variables in Y biplot. }
+  \item{ BB }{ Scores of X1 variables in X1 biplot. }
+  \item{ Cy }{ Object scores in Y biplot. }
+  \item{ Cx }{ Object scores in X1 biplot. }
 }
 
 \references{ 

Modified: branches/1.11-0/man/cca.Rd
===================================================================
--- branches/1.11-0/man/cca.Rd	2008-02-16 14:16:33 UTC (rev 217)
+++ branches/1.11-0/man/cca.Rd	2008-02-16 16:19:46 UTC (rev 218)
@@ -6,8 +6,8 @@
 \alias{rda}
 \alias{rda.default}
 \alias{rda.formula}
+\concept{ordination}
 
-
 \title{ [Partial] [Constrained] Correspondence Analysis and Redundancy
   Analysis } 
 \description{
@@ -37,16 +37,16 @@
     Can be missing. }
   \item{Z}{ Conditioning matrix, the effect of which is removed
     (`partialled out') before next step. Can be missing.}
-  \item{scale}{Scale species to unit variance (like correlations do).}
-  \item{...}{Other parameters for \code{print} or \code{plot} functions
+  \item{scale}{Scale species to unit variance (like correlations).}
+  \item{...}{Other arguments for \code{print} or \code{plot} functions
     (ignored in other functions).}
 }
 \details{
-  Since their introduction (ter Braak 1986), constrained or canonical
-  correspondence analysis, and its spin-off, redundancy analysis have
+  Since their introduction (ter Braak 1986), constrained, or canonical,
+  correspondence analysis and its spin-off, redundancy analysis, have
   been the most popular ordination methods in community ecology.
   Functions \code{cca} and \code{rda} are  similar to popular
-  proprietary software \code{Canoco}, although implementation is
+  proprietary software \code{Canoco}, although the implementation is
   completely different.  The functions are based on Legendre &
   Legendre's (1998) algorithm: in \code{cca}
   Chi-square transformed data matrix is subjected to weighted linear
@@ -55,14 +55,17 @@
   decomposition (\code{\link{svd}}). Function \code{rda} is similar, but uses
   ordinary, unweighted linear regression and unweighted SVD.
 
-  The functions can be called either with matrix entries for community
+  The functions can be called either with matrix-like entries for community
   data and constraints, or with formula interface.  In general, the
   formula interface is preferred, because it allows a better control of
   the model and allows factor constraints.
 
-  In matrix interface, the
-  community data matrix \code{X} must be given, but any other data
-  matrix can be omitted, and the corresponding stage of analysis is
+  In the following sections, \code{X}, \code{Y} and \code{Z}, although
+  referred to as matrices, are more commonly data frames.
+
+  In the matrix interface, the
+  community data matrix \code{X} must be given, but the other data
+  matrices may be omitted, and the corresponding stage of analysis is
   skipped.  If matrix \code{Z} is supplied, its effects are removed from
   the community matrix, and the residual matrix is submitted to the next
   stage.  This is called `partial' correspondence or redundancy
@@ -85,9 +88,9 @@
   \code{\link{contrasts}} are honoured in \code{\link{factor}}
   variables.  The formula can include a special term \code{Condition}
   for conditioning variables (``covariables'') ``partialled out'' before
-  analysis.  So the following commands are equivalent: \code{cca(X, y,
-    z)}, \code{cca(X ~ y + Condition(z))}, where \code{y} and \code{z}
-  refer to single variable constraints and conditions.
+  analysis.  So the following commands are equivalent: \code{cca(X, Y,
+    Z)}, \code{cca(X ~ Y + Condition(Z))}, where \code{Y} and \code{Z}
+  refer to constraints and conditions matrices respectively.
 
   Constrained correspondence analysis is indeed a constrained method:
   CCA does not try to display all variation in the
@@ -106,15 +109,14 @@
   clear and strong \emph{a priori} hypotheses on constraints and is not
   interested in the major structure in the data set.  
 
-  CCA is able to correct a common
-  curve artefact in correspondence analysis by
-  forcing the configuration into linear constraints.  However, the curve
-  artefact can be avoided only with a low number of constraints that do
-  not have a curvilinear relation with each other.  The curve can reappear
-  even with two badly chosen constraints or a single factor.  Although
-  the formula
-  interface makes easy to include polynomial or interaction terms, such
-  terms often allow curve artefact (and are difficult to interpret), and
+  CCA is able to correct the curve artefact commonly found in
+  correspondence analysis by forcing the configuration into linear
+  constraints.  However, the curve artefact can be avoided only with a
+  low number of constraints that do not have a curvilinear relation with
+  each other.  The curve can reappear even with two badly chosen
+  constraints or a single factor.  Although the formula interface makes
+  easy to include polynomial or interaction terms, such terms often
+  produce curved artefacts (that are difficult to interpret), these
   should probably be avoided.
 
   According to folklore, \code{rda} should be used with ``short
@@ -128,9 +130,9 @@
   the effect of some
   conditioning or ``background'' or ``random'' variables or
   ``covariables'' before CCA proper.  In fact, pCCA compares models
-  \code{cca(X ~ z)} and \code{cca(X ~ y + z)} and attributes their
-  difference to the effect of \code{y} cleansed of the effect of
-  \code{z}.  Some people have used the method for extracting
+  \code{cca(X ~ Z)} and \code{cca(X ~ Y + Z)} and attributes their
+  difference to the effect of \code{Y} cleansed of the effect of
+  \code{Z}.  Some people have used the method for extracting
   ``components of variance'' in CCA.  However, if the effect of
   variables together is stronger than sum of both separately, this can
   increase total Chi-square after ``partialling out'' some
@@ -148,7 +150,7 @@
 
   Function \code{rda} returns an object of class \code{rda} which
   inherits from class \code{cca} and is described in \code{\link{cca.object}}.
-  The scaling used in \code{rda} scores is desribed in a separate
+  The scaling used in \code{rda} scores is described in a separate
   vignette with this package.
 }
 \references{ The original method was by ter Braak, but the current
@@ -158,15 +160,15 @@
   ed. Elsevier.
 
   McCune, B. (1997) Influence of noisy environmental data on canonical
-  correspondence analysis. \emph{Ecology} 78, 2617-2623.
+  correspondence analysis. \emph{Ecology} \strong{78}, 2617-2623.
   
   Palmer, M. W. (1993) Putting things in even better order: The
-  advantages of canonical correspondence analysis.  \emph{Ecology} 74,
-  2215-2230. 
+  advantages of canonical correspondence analysis.  \emph{Ecology}
+  \strong{74},2215-2230. 
   
   Ter Braak, C. J. F. (1986) Canonical Correspondence Analysis: a new
   eigenvector technique for multivariate direct gradient
-  analysis. \emph{Ecology} 67, 1167-1179.
+  analysis. \emph{Ecology} \strong{67}, 1167-1179.
   
 }
 \author{

Modified: branches/1.11-0/man/cca.object.Rd
===================================================================
--- branches/1.11-0/man/cca.object.Rd	2008-02-16 14:16:33 UTC (rev 217)
+++ branches/1.11-0/man/cca.object.Rd	2008-02-16 16:19:46 UTC (rev 218)
@@ -15,7 +15,7 @@
 
 \value{
   A \code{cca} object has the following elements:
-  \item{call }{function call.}
+  \item{call }{the function call.}
   \item{colsum, rowsum }{Column and row sums in \code{cca}.  In
     \code{rda}, item \code{colsum} contains standard deviations of
     species and \code{rowsum} is \code{NA}.}
@@ -42,23 +42,23 @@
     component.
     Items \code{pCCA}, \code{CCA} and \code{CA} have similar
     structure, and contain following items:
-    \item{alias}{The names of the aliased constraints or conditions.
+    \item{\code{alias}}{The names of the aliased constraints or conditions.
       Function \code{\link{alias.cca}} does not access this item
       directly, but it finds the aliased variables and their defining
-      equations from the item \code{QR}.}
-    \item{biplot}{Biplot scores of constraints.  Only in \code{CCA}.}
+      equations from the \code{QR} item.}
+    \item{\code{biplot}}{Biplot scores of constraints.  Only in \code{CCA}.}
     \item{centroids}{(Weighted) centroids of factor levels of
       constraints. Only in \code{CCA}. Missing if the ordination was not
     called with \code{formula}.}
-    \item{eig}{Eigenvalues of axes. In \code{CCA} and \code{CA}.}
-    \item{envcentre}{(Weighted) means of the original constraining or
+    \item{\code{eig}}{Eigenvalues of axes. In \code{CCA} and \code{CA}.}
+    \item{\code{envcentre}}{(Weighted) means of the original constraining or
       conditioning variables. In \code{pCCA} and in \code{CCA}.}
-    \item{Fit}{The fitted values of standardized data matrix after
+    \item{\code{Fit}}{The fitted values of standardized data matrix after
       fitting conditions. Only in \code{pCCA}.}
-    \item{QR}{The QR decomposition of explanatory variables as produced
+    \item{\code{QR}}{The QR decomposition of explanatory variables as produced
       by \code{\link{qr}}. 
       The constrained ordination 
-      algorithm is based on \code{QR} decomposition of constraints and
+      algorithm is based on QR decomposition of constraints and
       conditions (environmental data).  The environmental data
       are first centred in \code{rda} or weighted and centred in
       \code{cca}.  The QR decomposition is used in many functions that
@@ -69,33 +69,33 @@
       \code{\link{predict.cca}}, \code{\link{predict.rda}},
       \code{\link{calibrate.cca}}.  For possible uses of this component,
       see \code{\link{qr}}. In \code{pCCA} and \code{CCA}.} 
-    \item{rank}{The rank of the component.}
-    \item{tot.chi}{Total inertia or the sum of all eigenvalues of the
+    \item{\code{rank}}{The rank of the component.}
+    \item{\code{tot.chi}}{Total inertia or the sum of all eigenvalues of the
       component.}
-    \item{u}{(Weighted) orthonormal site scores.  Please note that
+    \item{\code{u}}{(Weighted) orthonormal site scores.  Please note that
       scaled scores are not stored in the \code{cca} object, but they
       are made when the object is accessed with functions like
       \code{\link{scores.cca}}, \code{\link{summary.cca}} or
       \code{\link{plot.cca}}, or their \code{rda} variants.   Only in
-      \code{CCA} and \code{CA}.  In \code{CCA} component these are the
-      so-called linear combination scores. }
-    \item{u.eig}{\code{u} scaled by eigenvalues.  There is no guarantee
-      that any \code{.eig} variants of scores will be kept in the future
-      releases.}
-    \item{v}{(Weighted) orthonormal species scores.  If missing species
+      \code{CCA} and \code{CA}.  In the \code{CCA} component these are
+      the so-called linear combination scores. }
+    \item{\code{u.eig}}{\code{u} scaled by eigenvalues.  There is no
+      guarantee that any \code{.eig} variants of scores will be kept in
+      the future releases.}
+    \item{\code{v}}{(Weighted) orthonormal species scores.  If missing species
       were omitted from the analysis, this will contain
       attribute \code{\link{na.action}} that lists the
       omitted species. Only in \code{CCA} and \code{CA}.}
-    \item{v.eig}{\code{v} weighted by eigenvalues.}
-    \item{wa}{Site scores found as weighted averages (\code{cca}) or
+    \item{\code{v.eig}}{\code{v} weighted by eigenvalues.}
+    \item{\code{wa}}{Site scores found as weighted averages (\code{cca}) or
       weighted sums (\code{rda}) of 
       \code{v} with weights \code{Xbar}, but the multiplying effect of
       eigenvalues  removed. These often are known as WA scores in
       \code{cca}. Only in  \code{CCA}.}
-    \item{wa.eig}{The direct result of weighted avaraging or weighted
+    \item{\code{wa.eig}}{The direct result of weighted avaraging or weighted
       summation  (matrix multiplication)
       with the resulting eigenvalue inflation.}
-    \item{Xbar}{The standardized data matrix after previous stages of
+    \item{\code{Xbar}}{The standardized data matrix after previous stages of
       analysis. In \code{CCA} this is after possible \code{pCCA} or
       after partialling out the effects of conditions, and in \code{CA}
       after both \code{pCCA} and \code{CCA}. In \code{\link{cca}} the

Modified: branches/1.11-0/man/decorana.Rd
===================================================================
--- branches/1.11-0/man/decorana.Rd	2008-02-16 14:16:33 UTC (rev 217)
+++ branches/1.11-0/man/decorana.Rd	2008-02-16 16:19:46 UTC (rev 218)
@@ -8,6 +8,7 @@
 \alias{scores.decorana}
 \alias{points.decorana}
 \alias{text.decorana}
+\concept{ordination}
 
 \title{Detrended Correspondence Analysis and Basic Reciprocal Averaging }
 \description{
@@ -15,24 +16,32 @@
   averaging or orthogonal correspondence analysis.
 }
 \usage{
-decorana(veg, iweigh=0, iresc=4, ira=0, mk=26, short=0, before=NULL,
-         after=NULL)
+decorana(veg, iweigh=0, iresc=4, ira=0, mk=26, short=0,
+         before=NULL, after=NULL)
+
 \method{plot}{decorana}(x, choices=c(1,2), origin=TRUE,
      display=c("both","sites","species","none"),
-     cex = 0.8, cols = c(1,2), type, xlim, ylim,...)
-\method{text}{decorana}(x, display = c("sites", "species"), labels, choices = 1:2, 
-     origin = TRUE, select,  ...)  
-\method{points}{decorana}(x, display = c("sites", "species"), choices = 1:2, 
-     origin = TRUE, select, ...)  
+     cex = 0.8, cols = c(1,2), type, xlim, ylim, ...)
+
+\method{text}{decorana}(x, display = c("sites", "species"), labels,
+     choices = 1:2, origin = TRUE, select,  ...)
+
+\method{points}{decorana}(x, display = c("sites", "species"),
+       choices=1:2, origin = TRUE, select, ...)
+
 \method{summary}{decorana}(object, digits=3, origin=TRUE,
-     display=c("both", "species","sites","none"), ...)
+        display=c("both", "species","sites","none"), ...)
+
 \method{print}{summary.decorana}(x, head = NA, tail = head, ...)
+
 downweight(veg, fraction = 5)
-\method{scores}{decorana}(x, display=c("sites","species"), choices =1:4, origin=TRUE, ...)
+
+\method{scores}{decorana}(x, display=c("sites","species"), choices=1:4,
+       origin=TRUE, ...)
 }
 
 \arguments{
-  \item{veg}{Community data matrix. }
+  \item{veg}{Community data, a matrix-like object. }
   \item{iweigh}{Downweighting of rare species (0: no). }
   \item{iresc}{Number of rescaling cycles (0: no rescaling). }
   \item{ira}{Type of analysis (0: detrended, 1: basic reciprocal averaging). }
@@ -58,40 +67,39 @@
   \item{head, tail}{Number of rows printed from the head and tail of
     species and site scores. Default \code{NA} prints all.}
   \item{fraction}{Abundance fraction where downweighting begins.}
-  \item{...}{Other parameters for \code{plot} function.}
+  \item{...}{Other arguments for \code{plot} function.}
   }
 
 \details{
   In late 1970s, correspondence analysis became the method of choice for
-  ordination in vegetation science, since it seemed to be able to better cope
-  with non-linear species responses  than principal components
-  analysis.  However, even correspondence analysis produced arc-shaped
-  configuration of a single gradient.  Mark Hill developed
-  detrended correspondence analysis to correct two assumed `faults' in
+  ordination in vegetation science, since it seemed better able to cope 
+  with non-linear species responses than principal components
+  analysis. However, even correspondence analysis can produc an arc-shaped
+  configuration of a single gradient. Mark Hill developed detrended
+  correspondence analysis to correct two assumed `faults' in 
   correspondence analysis: curvature of straight gradients and packing
   of sites at the ends of the gradient.  
 
   The curvature is removed by replacing the orthogonalization of axes
-  with detrending.  In orthogonalization the successive axes are made
+  with detrending.  In orthogonalization successive axes are made
   non-correlated, but detrending should remove all systematic dependence
-  between axes.  Detrending is made using a five-segment smoothing
-  window with weights (1,2,3,2,1) on \code{mk} segments -- which indeed
+  between axes.  Detrending is performed using a five-segment smoothing
+  window with weights (1,2,3,2,1) on \code{mk} segments --- which indeed
   is more robust than the suggested alternative of detrending by
-  polynomials. The
-  packing of sites at the ends of the gradient is undone by rescaling
-  the axes after extraction.  After rescaling, the axis is supposed to be
-  scaled by `SD' units, so that the average width of Gaussian species
-  responses is supposed to be one over whole axis.  Other innovations
-  were the piecewise linear transformation of species abundances and
-  downweighting of rare species which were regarded to have an
-  unduly high influence on ordination axes.  
+  polynomials. The packing of sites at the ends of the gradient is
+  undone by rescaling the axes after extraction.  After rescaling, the
+  axis is supposed to be scaled by `SD' units, so that the average width
+  of Gaussian species responses is supposed to be one over whole axis.
+  Other innovations were the piecewise linear transformation of species
+  abundances and downweighting of rare species which were regarded to
+  have an unduly high influence on ordination axes.
 
   It seems that detrending actually works by twisting the ordination
   space, so that the results look non-curved in two-dimensional projections
-  (`lolly paper effect').  As a result, the points have usually an
-  easily recognized triangle or diamond shaped pattern, obviously as a
-  detrending artefact.  Rescaling works differently than commonly
-  presented, too.  \code{Decorana} does not use, or even evaluate, the
+  (`lolly paper effect').  As a result, the points usually have an
+  easily recognized triangular or diamond shaped pattern, obviously an
+  artefact of detrendingt.  Rescaling works differently than commonly
+  presented, too. \code{decorana} does not use, or even evaluate, the
   widths of species responses.  Instead, it tries to equalize the
   weighted variance of species scores on axis segments (parameter
   \code{mk} has only a small effect, since \code{decorana} finds the
@@ -100,84 +108,84 @@
   model, where all species initially have unit width responses and
   equally spaced modes.
 
-  Function \code{summary} prints the ordination scores,
+  The \code{summary} method prints the ordination scores,
   possible prior weights used in downweighting, and the marginal totals
-  after applying these weights. Function \code{plot} plots
+  after applying these weights. The \code{plot} method plots
   species and site scores.  Classical \code{decorana} scaled the axes
   so that smallest site score was 0 (and smallest species score was
   negative), but \code{summary}, \code{plot} and
-  \code{scores}  use the true origin, unless \code{origin = FALSE}.
+  \code{scores} use the true origin, unless \code{origin = FALSE}.
 
   In addition to proper eigenvalues, the function also reports `decorana
-  values' in detrended analysis. These are the values that the legacy
-  code of \code{decorana} returns as `eigenvalues'.
-  They are estimated internally during
-  iteration, and it seems that detrending interferes the estimation
-  so that these values are generally too low and have unclear
-  interpretation. Moreover, `decorana values' are estimated before
-  rescaling which will change the eigenvalues. The
-  proper eigenvalues are estimated after extraction of the axes and
-  they are the ratio of biased weighted variances of site and
-  species scores even in detrended and rescaled solutions. The
+  values' in detrended analysis. These `decorana values' are the values
+  that the legacy code of \code{decorana} returns as `eigenvalues'.
+  They are estimated internally during iteration, and it seems that
+  detrending interferes the estimation so that these values are
+  generally too low and have unclear interpretation. Moreover, `decorana
+  values' are estimated before rescaling which will change the
+  eigenvalues. The proper eigenvalues are estimated after extraction of
+  the axes and they are the ratio of biased weighted variances of site
+  and species scores even in detrended and rescaled solutions. The
   `decorana values' are provided only for the the compatibility with
   legacy software, and they should not be used.
 }
 \value{
-  Function returns an object of class \code{decorana}, which has
+  \code{decorana} returns an object of class \code{"decorana"}, which has
   \code{print}, \code{summary} and \code{plot} methods.
 }
 \references{
   Hill, M.O. and Gauch, H.G. (1980). Detrended correspondence analysis:
-  an improved ordination technique. \emph{Vegetatio} 42, 47--58.
+  an improved ordination technique. \emph{Vegetatio} \strong{42},
+  47--58.
 
   Oksanen, J. and Minchin, P.R. (1997). Instability of ordination
   results under changes in input data order: explanations and
-  remedies. \emph{Journal of Vegetation Science} 8, 447--454.
+  remedies. \emph{Journal of Vegetation Science} \strong{8}, 447--454.
 }
-\author{Mark O. Hill wrote the original Fortran code, \R port was by Jari
-  Oksanen.  }
+\author{Mark O. Hill wrote the original Fortran code, the \R port was by
+  Jari Oksanen. }
 \note{
-  Function \code{decorana} uses the central numerical engine of the
-  original Fortran code (which is in public domain), or about 1/3 of the
-  original program.  I have tried to implement the original behaviour,
-  although a great part of preparatory steps were written in \R
-  language, and may differ somewhat from the original code. However,
+  \code{decorana} uses the central numerical engine of the
+  original Fortran code (which is in the public domain), or about 1/3 of
+  the original program.  I have tried to implement the original
+  behaviour, although a great part of preparatory steps were written in
+  \R language, and may differ somewhat from the original code. However,
   well-known bugs are corrected and strict criteria used (Oksanen &
-  Minchin 1997).
+  Minchin 1997). 
 
-  Please
-  note that there really is no need for piecewise transformation or even
-  downweighting within \code{decorana}, since there are more powerful
-  and extensive alternatives in \R, but these options are included for
-  compliance with the original software.  If different fraction of
-  abundance is needed in downweighting, function \code{downweight} must
-  be applied before \code{decorana}.  Function \code{downweight} 
-  indeed can be applied prior to correspondence analysis, and so it can be
-  used together with \code{\link{cca}}, too.
+  Please note that there really is no need for piecewise transformation
+  or even downweighting within \code{decorana}, since there are more
+  powerful and extensive alternatives in \R, but these options are
+  included for compliance with the original software.  If a different
+  fraction of abundance is needed in downweighting, function
+  \code{downweight} must be applied before \code{decorana}.  Function
+  \code{downweight} indeed can be applied prior to correspondence
+  analysis, and so it can be used together with \code{\link{cca}}, too.
 
   The function finds only four axes: this is not easily changed.
 }
 
+\seealso{
+  For unconstrained ordination, non-metric multidimensional scaling in
+  \code{\link[MASS]{isoMDS}} may be more robust (see also
+  \code{\link{metaMDS}}).  Constrained (or
+  `canonical') correspondence analysis can be made with
+  \code{\link{cca}}.  Orthogonal correspondence analysis can be
+  made with \code{\link[multiv]{ca}}, or with \code{decorana} or
+  \code{\link{cca}}, but the scaling of results vary (and the one in
+  \code{decorana} correspondes to \code{scaling = -1} in
+  \code{\link{cca}}.).
+  See \code{\link{predict.decorana}} for adding new points to an
+  ordination.
+}
 
- \seealso{
-   For unconstrained ordination, non-metric multidimensional scaling in
-   \code{\link[MASS]{isoMDS}} may be more robust (see also
-   \code{\link{metaMDS}}).  Constrained (or
-   `canonical') correspondence analysis can be made with
-   \code{\link{cca}}.  Orthogonal correspondence analysis can be
-   made with \code{\link[multiv]{ca}}, or with \code{decorana} or
-   \code{\link{cca}}, but the scaling of results vary (and the one in
-   \code{decorana} correspondes to \code{scaling = -1} in
-   \code{\link{cca}}.).
-   See \code{\link{predict.decorana}} for adding new points to ordination. 
- }
-
 \examples{
 data(varespec)
 vare.dca <- decorana(varespec)
 vare.dca
 summary(vare.dca)
 plot(vare.dca)
+
 ### the detrending rationale:
 gaussresp <- function(x,u) exp(-(x-u)^2/2)
 x <- seq(0,6,length=15) ## The gradient
@@ -189,6 +197,7 @@
 plot(scores(decorana(pack, ira=1)), asp=1, type="b", main="CA")
 plot(scores(decorana(pack)), asp=1, type="b", main="DCA")
 plot(scores(cca(pack ~ x), dis="sites"), asp=1, type="b", main="CCA")
+
 ### Let's add some noise:
 noisy <- (0.5 + runif(length(pack)))*pack
 par(mfrow=c(2,1))
@@ -200,6 +209,6 @@
 plot(scores(decorana(noisy)), type="b", main="DCA", asp=1)
 plot(scores(cca(noisy ~ x), dis="sites"), asp=1, type="b", main="CCA")
 par(opar)
-  }
+}
 \keyword{ multivariate }
 

Modified: branches/1.11-0/man/decostand.Rd
===================================================================
--- branches/1.11-0/man/decostand.Rd	2008-02-16 14:16:33 UTC (rev 217)
+++ branches/1.11-0/man/decostand.Rd	2008-02-16 16:19:46 UTC (rev 218)
@@ -8,14 +8,16 @@
 methods for community ecologists.
 }
 \usage{
-decostand(x, method, MARGIN, range.global, na.rm = FALSE)
+decostand(x, method, MARGIN, range.global, na.rm=FALSE)
+
 wisconsin(x)
 }
 
 \arguments{
-  \item{x}{Community data matrix.}
-  \item{method}{Standardization method.}
-  \item{MARGIN}{Margin, if default is not acceptable.}
+  \item{x}{Community data, a matrix-like object.}
+  \item{method}{Standardization method. See Details for available options.}
+  \item{MARGIN}{Margin, if default is not acceptable. \code{1} = rows,
+    and \code{2} = columns of \code{x}.}
   \item{range.global}{Matrix from which the range is found in
     \code{method = "range"}.  This allows using same ranges across
     subsets of data.  The dimensions of \code{MARGIN} must match with
@@ -28,21 +30,21 @@
   \itemize{
     \item \code{total}: divide by margin total (default \code{MARGIN = 1}).
     \item \code{max}: divide by margin maximum (default \code{MARGIN = 2}).
-    \item \code{freq}: divide by margin maximum and multiply by number of
-    non-zero items, so that the average of non-zero entries is one
-    (Oksanen 1983; default \code{MARGIN = 2}).
+    \item \code{freq}: divide by margin maximum and multiply by the
+    number of non-zero items, so that the average of non-zero entries is
+    one (Oksanen 1983; default \code{MARGIN = 2}).
     \item \code{normalize}: make margin sum of squares equal to one (default
     \code{MARGIN = 1}).
     \item \code{range}: standardize values into range 0 \dots 1 (default
     \code{MARGIN = 2}).  If all values are constant, they will be
     transformed to 0.
-    \item \code{standardize}: scale into zero mean and unit variance
+    \item \code{standardize}: scale \code{x} to zero mean and unit variance
     (default \code{MARGIN = 2}).
-    \item \code{pa}: scale into presence/absence scale (0/1).
+    \item \code{pa}: scale \code{x} to presence/absence scale (0/1).
     \item \code{chi.square}: divide by row sums and square root of
     column sums, and adjust for square root of matrix total
-    (Legendre & Gallagher 2001). When used with Euclidean
-    distance, the matrix should be similar to the  the
+    (Legendre & Gallagher 2001). When used with the Euclidean
+    distance, the distances should be similar to the the
     Chi-square distance used in correspondence analysis. However, the
     results from \code{\link{cmdscale}} would still differ, since
     CA is a weighted ordination method (default \code{MARGIN =
@@ -53,19 +55,18 @@
   Standardization, as contrasted to transformation, means that the
   entries are transformed relative to other entries.
 
-  All methods have a default margin.  \code{MARGIN=1} means rows (sites
-  in a
-  normal data set) and \code{MARGIN=2} means columns (species in a normal
-  data set).
+  All methods have a default margin. \code{MARGIN=1} means rows (sites
+  in a normal data set) and \code{MARGIN=2} means columns (species in a
+  normal data set).
 
   Command \code{wisconsin} is a shortcut to common Wisconsin double
   standardization where species (\code{MARGIN=2}) are first standardized
   by maxima (\code{max}) and then sites (\code{MARGIN=1}) by
   site totals (\code{tot}).
 
-  Most  standardization methods will give non-sense results with
+  Most standardization methods will give nonsense results with
   negative data entries that normally should not occur in the community
-  data.  If there are empty sites  or species (or constant with
+  data. If there are empty sites or species (or constant with
   \code{method =  "range"}), many standardization will change these into
   \code{NaN}.  
 }
@@ -79,12 +80,12 @@
 
 \references{
   Legendre, P. & Gallagher, E.D. (2001) Ecologically meaningful
-  transformations for ordination of species data. \emph{Oecologia} 129:
-  271--280.
+  transformations for ordination of species data. \emph{Oecologia}
+  \strong{129}; 271--280.
 
   Oksanen, J. (1983) Ordination of boreal heath-like vegetation with
   principal component analysis, correspondence analysis and
-  multidimensional scaling. \emph{Vegetatio} 52, 181--189.
+  multidimensional scaling. \emph{Vegetatio} \strong{52}; 181--189.
   }
 
 \examples{
@@ -92,10 +93,10 @@
 sptrans <- decostand(varespec, "max")
 apply(sptrans, 2, max)
 sptrans <- wisconsin(varespec)
+
 # Chi-square: Similar but not identical to Correspondence Analysis.
 sptrans <- decostand(varespec, "chi.square")
 plot(procrustes(rda(sptrans), cca(varespec)))
 }
 \keyword{ multivariate}%-- one or more ...
 \keyword{ manip }
-



More information about the Vegan-commits mailing list