Allow finer control of which eignevalues are returned by cca method;

  implements wish of #207 - closes #207

R/eigenvals.R

@@ -54,15 +54,32 @@
 
 ## concatenate constrained and unconstrained eigenvalues in cca, rda
 ## and capscale (vegan) -- ignore pCCA component
-`eigenvals.cca` <- function(x, constrained = FALSE, ...)
+`eigenvals.cca` <- function(x, model = c("all", "unconstrained", "constrained"),
+                            constrained = NULL, ...)
 {
-   if (constrained)
-       out <- x$CCA$eig
-   else
-       out <- c(x$CCA$eig, x$CA$eig)
-   if (!is.null(out))
-       class(out) <- "eigenvals"
-   out
+    out <- if (!is.null(constrained)) {
+        ## old behaviour
+        message("Argument `constrained` is deprecated; use `model` instead.")
+        if (constrained) {
+            x$CCA$eig
+        } else {
+            c(x$CCA$eig, x$CA$eig)
+        }
+    } else {
+        ## new behaviour
+        model <- match.arg(model)
+        if (identical(model, "all")) {
+            c(x$CCA$eig, x$CA$eig)
+        } else if (identical(model, "unconstrained")) {
+            x$CA$eig
+        } else {
+            x$CCA$eig
+        }
+    }
+    if (!is.null(out)) {
+        class(out) <- "eigenvals"
+    }
+    out
 }
 
 ## wcmdscale (in vegan)

man/eigenvals.Rd

@@ -21,23 +21,29 @@
 }
 \usage{
 eigenvals(x, ...)
-\method{eigenvals}{cca}(x, constrained = FALSE, ...)
+\method{eigenvals}{cca}(x, model = c("all", "unconstrained", "constrained"),
+          constrained = NULL, ...)
 \method{summary}{eigenvals}(object, ...)
 }
 
 \arguments{
   \item{x}{
     An object from which to extract eigenvalues.
-}
+  }
   \item{object}{
     An \code{eigenvals} result object.
-}
-   \item{constrained}{
-    Return only constrained eigenvalues.
-}
-   \item{\dots}{
+  }
+  \item{model}{
+    Which eigenvalues to return for objects that inherit from class
+    \code{"cca"} only.
+  }
+  \item{constrained}{
+    Return only constrained eigenvalues. Deprecated as of vegan
+    2.5-0. Use \code{model} instead.
+  }
+  \item{\dots}{
     Other arguments to the functions (usually ignored)
-}
+  }
 }
 
 \details{
@@ -103,6 +109,9 @@ mod <- cca(varespec ~ Al + P + K, varechem)
 ev <- eigenvals(mod)
 ev
 summary(ev)
+
+## choose which eignevalues to return
+eigenvals(mod, model = "unconstrained")
 }
 \keyword{ multivariate }