[Vegan-commits] r1034 - in pkg/vegan: R inst man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Tue Oct 6 21:16:13 CEST 2009
Author: jarioksa
Date: 2009-10-06 21:16:03 +0200 (Tue, 06 Oct 2009)
New Revision: 1034
Added:
pkg/vegan/man/ordistep.Rd
Modified:
pkg/vegan/R/ordistep.R
pkg/vegan/inst/ChangeLog
pkg/vegan/man/add1.cca.Rd
Log:
ordistep should be functional and have similar UI as step
Modified: pkg/vegan/R/ordistep.R
===================================================================
--- pkg/vegan/R/ordistep.R 2009-10-06 16:20:49 UTC (rev 1033)
+++ pkg/vegan/R/ordistep.R 2009-10-06 19:16:03 UTC (rev 1034)
@@ -1,18 +1,45 @@
`ordistep` <-
- function(object, scope, Pin = 0.05, Pout = 0.1,
- pstep = 100, perm.max = 1000, steps=50, trace = TRUE, ...)
+ function(object, scope, direction =c("both", "backward", "foreward"),
+ Pin = 0.05, Pout = 0.1, pstep = 100, perm.max = 1000,
+ steps=50, trace = TRUE, ...)
{
if (!inherits(object, "cca"))
- stop("function can be only used to 'cca' and related objects")
- if (missing(scope))
- stop("absolutely needs scope")
- mod <- eval.parent(update(object, . ~ 1))
+ stop("function can be only used with 'cca' and related objects")
+ ## handling 'direction' and 'scope' directly copied from
+ ## stats::step()
+ md <- missing(direction)
+ direction <- match.arg(direction)
+ backward <- direction == "both" | direction == "backward"
+ forward <- direction == "both" | direction == "forward"
+ ffac <- attr(terms(object), "factors")
+ if (missing(scope)) {
+ fdrop <- numeric(0)
+ fadd <- ffac
+ if (md)
+ forward <- FALSE
+ }
+ else {
+ if (is.list(scope)) {
+ fdrop <- if (!is.null(fdrop <- scope$lower))
+ attr(terms(update.formula(object, fdrop)), "factors")
+ else numeric(0)
+ fadd <- if (!is.null(fadd <- scope$upper))
+ attr(terms(update.formula(object, fadd)), "factors")
+ }
+ else {
+ fadd <- if (!is.null(fadd <- scope))
+ attr(terms(update.formula(object, scope)), "factors")
+ fdrop <- numeric(0L)
+ }
+ }
+ scope <- factor.scope(ffac, list(add = fadd, drop = fdrop))
+ mod <- object
for (i in 1:steps){
change <- NULL
## Consider dropping
- if (length(drop.scope(mod))) {
- aod <- drop1(mod, test="perm", pstep = pstep, perm.max = perm.max,
- alpha = Pout)
+ if (backward && length(scope$drop)) {
+ aod <- drop1(mod, scope = scope$drop, test="perm", pstep = pstep,
+ perm.max = perm.max, alpha = Pout, trace = trace, ...)
aod <- aod[-1,]
o <- order(-aod[,5], aod[,4], aod[,2])
aod <- aod[o,]
@@ -24,6 +51,8 @@
if (aod[1,5] > Pout) {
change <- rownames(aod)[1]
mod <- eval.parent(update(mod, paste("~ .", change)))
+ scope <- factor.scope(attr(terms(mod), "factors"),
+ list(add = fadd, drop = fdrop))
if (trace) {
cat("\n")
print(mod$call)
@@ -31,9 +60,9 @@
}
}
## Consider adding
- if (length(add.scope(formula(mod), scope))) {
- aod <- add1(mod, scope = scope, test = "perm", pstep = pstep,
- perm.max = perm.max, alpha = Pin)
+ if (forward && length(scope$add)) {
+ aod <- add1(mod, scope = scope$add, test = "perm", pstep = pstep,
+ perm.max = perm.max, alpha = Pin, trace = trace, ...)
aod <- aod[-1,]
o <- order(aod[,5], aod[,4], aod[,2])
aod <- aod[o,]
@@ -45,6 +74,8 @@
if (aod[1,5] <= Pin) {
change <- rownames(aod)[1]
mod <- eval.parent(update(mod, paste( "~ .",change)))
+ scope <- factor.scope(attr(terms(mod), "factors"),
+ list(add = fadd, drop = fdrop))
if (trace) {
cat("\n")
print(mod$call)
Modified: pkg/vegan/inst/ChangeLog
===================================================================
--- pkg/vegan/inst/ChangeLog 2009-10-06 16:20:49 UTC (rev 1033)
+++ pkg/vegan/inst/ChangeLog 2009-10-06 19:16:03 UTC (rev 1034)
@@ -15,8 +15,8 @@
the function has both drop and add instead of only forward
selection, handles correctly factors, and works with cca(), rda()
and capscale(). On the other hand, it is much slower than
- forward.sel(). The 'scope' needs still work. Not yet documented
- (alias with add1.cca).
+ forward.sel(). The function has similar user interface as step():
+ it knows 'scope' and 'direction'.
* ordisurf: pushes out limits of convex hull so that contours
better cover corners and margins of points.
Modified: pkg/vegan/man/add1.cca.Rd
===================================================================
--- pkg/vegan/man/add1.cca.Rd 2009-10-06 16:20:49 UTC (rev 1033)
+++ pkg/vegan/man/add1.cca.Rd 2009-10-06 19:16:03 UTC (rev 1034)
@@ -1,7 +1,6 @@
\name{add1.cca}
\alias{add1.cca}
\alias{drop1.cca}
-\alias{ordistep}
\title{Add or Drop Single Terms to a Constrained Ordination Model }
\description{
@@ -37,12 +36,16 @@
Function \code{add1.cca} will implement a test for single term
additions that is not directly available in \code{\link{anova.cca}}.
- Functions are used implicitly in \code{\link{step}}. The
- \code{\link{deviance.cca}} and \code{\link{deviance.rda}} used in
- \code{\link{step}} have no firm basis, and setting argument
- \code{test = "permutation"} may help in getting useful insight into
- validity of model building. Meticulous use of \code{add1.cca} and
- \code{drop1.cca} will allow more judicious model building.
+ Functions are used implicitly in \code{\link{step}} and
+ \code{\link{ordistep}}. The \code{\link{deviance.cca}} and
+ \code{\link{deviance.rda}} used in \code{\link{step}} have no firm
+ basis, and setting argument \code{test = "permutation"} may help in
+ getting useful insight into validity of model building. Function
+ \code{\link{ordistep}} calls alternately \code{drop1.cca} and
+ \code{add1.cca} with argument \code{test = "permutation"} and
+ selects variables by their permutation \eqn{P}-values. Meticulous
+ use of \code{add1.cca} and \code{drop1.cca} will allow more
+ judicious model building.
The default \code{perm.max} is set to a low value, because
permutation tests can take a long time. It should be sufficient to
@@ -59,7 +62,7 @@
\seealso{ \code{\link{add1}}, \code{\link{drop1}} and
\code{\link{anova.cca}} for basic methods. You probably need these
- functions with \code{\link{step}}. Functions
+ functions with \code{\link{step}} and \code{link{ordistep}}. Functions
\code{\link{deviance.cca}} and \code{\link{extractAIC.cca}} are used
to produce the other arguments than test results in the
output. Functions \code{\link{cca}}, \code{\link{rda}} and
@@ -67,8 +70,10 @@
\examples{
data(dune)
data(dune.env)
-## Automatic model building with permutation tests
-step(rda(dune ~ 1, dune.env), reformulate(names(dune.env)), test="perm")
+## Automatic model building based on AIC but with permutation tests
+step(cca(dune ~ 1, dune.env), reformulate(names(dune.env)), test="perm")
+## The same, but based on permutation P-values
+ordistep(cca(dune ~ 1, dune.env), reformulate(names(dune.env)), perm.max=500)
## Manual model building
## -- define the maximal model for scope
mbig <- rda(dune ~ ., dune.env)
Added: pkg/vegan/man/ordistep.Rd
===================================================================
--- pkg/vegan/man/ordistep.Rd (rev 0)
+++ pkg/vegan/man/ordistep.Rd 2009-10-06 19:16:03 UTC (rev 1034)
@@ -0,0 +1,105 @@
+\name{ordistep}
+\Rdversion{1.1}
+\alias{ordistep}
+
+\title{
+ Choose a Model by Permutation Tests in Constrained Ordination
+}
+\description{
+ Automatic stepwise model building for constrained ordination methods
+ (\code{\link{cca}}, \code{\link{rda}}, \code{\link{capscale}}).
+ The function is modelled after \code{\link{step}} and can do forward,
+ backward and stepwise model selection.
+}
+\usage{
+ordistep(object, scope, direction = c("both", "backward", "foreward"), Pin = 0.05, Pout = 0.1, pstep = 100, perm.max = 1000, steps = 50, trace = TRUE, ...)
+}
+%- maybe also 'usage' for other objects documented here.
+\arguments{
+ \item{object}{
+ An ordination object inheriting from \code{\link{cca}}.
+}
+ \item{scope}{
+ Defines the range of models examined in the stepwise search.
+ This should be either a single formula, or a list containing
+ components \code{upper} and \code{lower}, both formulae.
+ See \code{\link{step}} for details.
+}
+ \item{direction}{
+ The mode of stepwise search, can be one of \code{"both"},
+ \code{"backward"}, or \code{"forward"}, with a default of \code{"both"}.
+ If the \code{scope} argument is missing the default for \code{direction}
+ is \code{"backward"}.
+}
+ \item{Pin, Pout}{
+ Limits of permutation \eqn{P}-values for adding (\code{Pin}) a term to
+ the model, or dropping (\code{Pout}) from the model. Term is added if
+ \eqn{P \le}{P <=} \code{Pin}, and removed if \eqn{P >} \code{Pout}.
+}
+ \item{pstep}{
+ Number of permutations in one step. See \code{\link{add1.cca}}.
+}
+ \item{perm.max}{
+ Maximum number of permutation in \code{\link{anova.cca}}.
+}
+ \item{steps}{
+ Maximum number of iteration steps of dropping and adding terms.
+}
+ \item{trace}{
+ If positive, information is printed during the model builing. Larger
+ values may give more information.
+}
+ \item{\dots}{
+ Any additional arguments to \code{\link{add1.cca}} and
+ \code{\link{drop1.cca}}.
+}
+}
+\details{
+ The basic functions for model choice in constrained ordination are
+ \code{\link{add1.cca}} and \code{\link{drop1.cca}}. With these functions,
+ ordination models can be chosen with standard \R\ function
+ \code{\link{step}} which bases the term choice on AIC. AIC-like
+ statistics for ordination are provided by functions
+ \code{\link{deviance.cca}} and \code{\link{extractAIC.cca}} (with
+ similar functions for \code{\link{rda}}). Actually, constrained
+ ordination methods do not have AIC, and therefore the \code{\link{step}}
+ may not be trusted. This function provides an alternative using
+ permutation \eqn{P}-values.
+
+ Function \code{ordistep} defines the model, \code{scope} of models
+ considered, and \code{direction} of the procedure similarly as
+ \code{\link{step}}. The function alternates with \code{drop} and
+ \code{add} steps and stops when the model was not changed during one
+ step. The \code{-} and \code{+} signs in the summary
+ table indicate which stage is performed. The number of permutations
+ is selected adaptively with respect to the defined decision limit. It
+ is often sensible to have \code{Pout} \eqn{>} \code{Pin} in stepwise
+ models to avoid cyclic adds and drops of single terms.
+}
+\value{
+ Function returns the chosen model.
+}
+
+\author{
+ Jari Oksanen
+}
+
+\seealso{
+ The function handles constrained ordination methods \code{\link{cca}},
+ \code{\link{rda}} and \code{\link{capscale}}. The underlying functions
+ are \code{\link{add1.cca}} and \code{\link{drop1.cca}}, and the
+ function is modelled after standard \code{\link{step}} (which also can
+ be used directly but uses AIC for model choice, see
+ \code{\link{extractAIC.cca}}).
+}
+\examples{
+## See add1.cca for another example
+data(dune)
+data(dune.env)
+mod1 <- rda(dune ~ ., dune.env)
+ordistep(mod1)
+ordistep(rda(dune ~ 1, dune.env), scope = formula(mod1))
+}
+
+\keyword{ multivariate }
+\keyword{ models }
More information about the Vegan-commits
mailing list