Merge branch 'issue-655': closes #655

NAMESPACE

@@ -5,7 +5,7 @@ useDynLib(vegan, .registration = TRUE)
 
 export(CCorA, MOStest, RsquareAdj, SSarrhenius, SSgitay, SSgleason,
 SSlomolino, adipart, adonis2, anosim, beals, betadisper, betadiver,
-bgdispersal, bioenv, bioenvdist, bstick, cIndexKM, calibrate, capscale,
+bgdispersal, bioenv, bioenvdist, bstick, cIndexKM, ca, calibrate, capscale,
 cascadeKM, cca, chaodist, contribdiv, clamtest, commsim, cutreeord,
 dbrda, decobackstand, decorana, decostand, designdist, designdist2,
 dist2xy, coverscale, dispweight, dispindmorisita, distconnected,
@@ -23,7 +23,7 @@ ordicluster, ordiellipse, ordigrid,
 ordihull, ordilabel, ordiplot, ordipointlabel, ordiresids,
 ordisegments, ordispider, ordisplom, ordistep, ordisurf,
 orditkplot, orditorp, ordixyplot, ordiYbar,
-pcnm, permatfull, permatswap, permustats, permutest,
+pca, pco, pcnm, permatfull, permatswap, permustats, permutest,
 poolaccum, postMDS, prc, prestondistr, prestonfit, procrustes,
 protest, radfit, radlattice, rankindex, rarefy, rarecurve, rareslope,
 raupcrick, rda, renyiaccum, renyi, rrarefy, scores,

R/ca.R

@@ -0,0 +1,11 @@
+`ca` <- function(X, ...) {
+  if (inherits(X, "formula")) {
+    stop("Argument 'X' was supplied a formula, which is not supported by 'ca()'",
+    call. = FALSE)
+  }
+  ord <- cca(X = X, ...)
+  # change the call to be from ca()
+  ord$call <- match.call()
+  class(ord) <- append(class(ord), "ca", after = 0)
+  ord
+}

R/pca.R

@@ -0,0 +1,11 @@
+`pca` <- function(X, scale = FALSE, ...) {
+  if (inherits(X, "formula")) {
+    stop("Argument 'X' was supplied a formula, which is not supported by 'pca()'",
+    call. = FALSE)
+  }
+  ord <- rda(X = X, scale = scale, ...)
+  # change the call to be from pca()
+  ord$call <- match.call()
+  class(ord) <- append(class(ord), "pca", after = 0)
+  ord
+}

R/pco.R

@@ -0,0 +1,11 @@
+`pco` <- function(X, ...) {
+  if (inherits(X, "formula")) {
+    stop("Argument 'X' was supplied a formula, which is not supported by 'pco()'",
+    call. = FALSE)
+  }
+  ord <- dbrda(X ~ 1, ...)
+  # change the call to be from pco()
+  ord$call <- match.call()
+  class(ord) <- append(class(ord), "pco", after = 0)
+  ord
+}

man/cca.Rd

@@ -5,6 +5,8 @@
 \alias{rda}
 \alias{rda.default}
 \alias{rda.formula}
+\alias{ca}
+\alias{pca}
 
 \title{ [Partial] [Constrained] Correspondence Analysis and Redundancy
   Analysis } 
@@ -23,6 +25,8 @@
   subset = NULL, ...)
 \method{cca}{default}(X, Y, Z, ...)
 \method{rda}{default}(X, Y, Z, scale=FALSE, ...)
+ca(X, ...)
+pca(X, scale=FALSE, ...)
 }
 
 \arguments{
@@ -57,7 +61,8 @@
     can contain variables in the working environment, \code{data} or
     species names of the community data.}
   \item{...}{Other arguments for \code{print} or \code{plot} functions
-    (ignored in other functions).}
+    (ignored in other functions). For \code{pca()} and \code{ca()},
+    arguments are passed to \code{rda()} and \code{cca()}, respectively.}
 }
 \details{
   Since their introduction (ter Braak 1986), constrained, or canonical,
@@ -76,10 +81,10 @@
   algorithm of \pkg{vegan}. The algorithm of CCA is similar, but
   involves standardization by row and column weights.
 
-  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. Some
+  The functions \code{cca()} and \code{rda()} 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. Some
   analyses of ordination results are only possible if model was fitted
   with formula (e.g., most cases of \code{\link{anova.cca}}, automatic
   model building).
@@ -165,6 +170,12 @@
   variation, and give negative \dQuote{components of variance}.  In general,
   such components of \dQuote{variance} are not to be trusted due to
   interactions between two sets of variables.
+
+  The unconstrained ordination methods, Principal Components Analysis (PCA) and
+  Correspondence Analysis (CA), may be performed using \code{pca()} and
+  \code{ca()}, which are simple wrappers around \code{rda()} and \code{cca()},
+  respectively. Functions \code{pca()} and \code{ca} can only be called with
+  matrix-like objects.
   
   The functions have \code{summary} and \code{plot} methods which are
   documented separately (see \code{\link{plot.cca}}, \code{\link{summary.cca}}).
@@ -205,14 +216,16 @@
 \seealso{
   
   This help page describes two constrained ordination functions,
-  \code{cca} and \code{rda}.  A related method, distance-based
-  redundancy analysis (dbRDA) is described separately
-  (\code{\link{capscale}}). All these functions return similar objects
-  (described in \code{\link{cca.object}}). There are numerous support
-  functions that can be used to access the result object. In the list
-  below, functions of type \code{cca} will handle all three constrained
-  ordination objects, and functions of \code{rda} only handle \code{rda}
-  and \code{\link{capscale}} results.
+  \code{cca} and \code{rda} and their corresponding unconstrained
+  ordination functions, \code{ca} and \code{pca}. A related method,
+  distance-based redundancy analysis (dbRDA) is described separately
+  (\code{\link{capscale}}), as is dbRDA's unconstrained variant,
+  principal coordinates analysis (PCO). All these functions return
+  similar objects (described in \code{\link{cca.object}}). There are
+  numerous support functions that can be used to access the result object.
+  In the list below, functions of type \code{cca} will handle all three
+  constrained ordination objects, and functions of \code{rda} only handle
+  \code{rda} and \code{\link{capscale}} results.
 
   The main plotting functions are \code{\link{plot.cca}} for all
   methods, and \code{\link{biplot.rda}} for RDA and dbRDA.  However,
@@ -279,4 +292,3 @@ dune.Manure <- rda(dune ~ Manure, dune.env)
 plot(dune.Manure) 
 }
 \keyword{ multivariate }
-

man/dbrda.Rd

@@ -1,8 +1,10 @@
 \name{dbrda}
 \alias{capscale}
 \alias{dbrda}
+\alias{pco}
 
-\title{[Partial] Distance-based Redundancy Analysis }
+\title{Principal Coordinates Analysis and [Partial] Distance-based
+Redundancy Analysis}
 
 \description{
 
@@ -18,9 +20,9 @@
   more useful, with other dissimilarity measures. Function
   \code{capscale} is a simplified version based on Euclidean
   approximation of dissimilarities. The functions can also perform
-  unconstrained principal coordinates analysis, optionally using
-  extended dissimilarities.
-
+  unconstrained principal coordinates analysis (PCO), optionally using
+  extended dissimilarities. \code{pco()} is a wrapper to \code{dbrda()},
+  which performs PCO.
 }
 
 \usage{
@@ -30,6 +32,7 @@ dbrda(formula, data, distance = "euclidean", sqrt.dist = FALSE,
 capscale(formula, data, distance = "euclidean", sqrt.dist = FALSE,
     comm = NULL, add = FALSE,  dfun = vegdist, metaMDSdist = FALSE,
     na.action = na.fail, subset = NULL, ...)
+pco(X, ...)
 }
 
 \arguments{
@@ -48,6 +51,7 @@ capscale(formula, data, distance = "euclidean", sqrt.dist = FALSE,
     special term \code{Condition} that defines variables to be
     \dQuote{partialled out} before constraints, just like in \code{\link{rda}}
     or \code{\link{cca}}. This allows the use of partial dbRDA.}
+  \item{X}{ Community data matrix. }
   \item{data}{ Data frame containing the variables on the right hand side of
     the model formula. }
   \item{distance}{The name of the dissimilarity (or distance) index if
@@ -95,7 +99,8 @@ capscale(formula, data, distance = "euclidean", sqrt.dist = FALSE,
      environment, \code{data} or species names of the community data
      (if given in the formula or as \code{comm} argument).}
    \item{\dots}{Other parameters passed to underlying functions (e.g.,
-     \code{\link{metaMDSdist}}).  }
+     \code{\link{metaMDSdist}}). For \code{pco()} argument are passed to
+     \code{dbrda()}. }
 }
 \details{
 
@@ -230,6 +235,8 @@ dbrda(varespec ~ N + P + K + Condition(Al), varechem, dist="bray",
 (m <- dbrda(varespec ~ N + P + K + Condition(Al), varechem, dist="jaccard"))
 ## add species scores
 sppscores(m) <- wisconsin(varespec)
+## pco
+pco(varespec, dist = "bray", sqrt.dist = TRUE)
 }
 \keyword{ multivariate }