[Vegan-commits] r489 - in pkg: R inst man

[noreply at r-forge.r-project.org]

Author: jarioksa
Date: 2008-08-28 12:39:42 +0200 (Thu, 28 Aug 2008)
New Revision: 489

Modified:
   pkg/R/capscale.R
   pkg/R/ordiParseFormula.R
   pkg/inst/ChangeLog
   pkg/man/vegan-internal.Rd
Log:
fixes in scope of ordiParseFormula and added developer docs

Modified: pkg/R/capscale.R
===================================================================
--- pkg/R/capscale.R	2008-08-28 07:46:24 UTC (rev 488)
+++ pkg/R/capscale.R	2008-08-28 10:39:42 UTC (rev 489)
@@ -51,7 +51,7 @@
     sol <- X$points[, 1:neig]
     fla <- update(formula, sol ~ .)
     environment(fla) <- environment()
-    d <- ordiParseFormula(fla, data)
+    d <- ordiParseFormula(fla, data, envdepth = 1)
     sol <- rda.default(d$X, d$Y, d$Z, ...)
     sol$tot.chi <- sol$tot.chi
     if (!is.null(sol$CCA)) {

Modified: pkg/R/ordiParseFormula.R
===================================================================
--- pkg/R/ordiParseFormula.R	2008-08-28 07:46:24 UTC (rev 488)
+++ pkg/R/ordiParseFormula.R	2008-08-28 10:39:42 UTC (rev 489)
@@ -1,10 +1,10 @@
 "ordiParseFormula" <-
-function (formula, data, xlev = NULL) 
+function (formula, data, xlev = NULL, envdepth = 2) 
 {
     Terms <- terms(formula, "Condition", data = data)
     flapart <- fla <- formula <- formula(Terms, width.cutoff = 500)
     specdata <- formula[[2]]
-    X <- eval.parent(specdata)
+    X <- eval.parent(specdata, n = envdepth)
     X <- as.matrix(X)
     indPartial <- attr(Terms, "specials")$Condition
     mf <- Z <- NULL

Modified: pkg/inst/ChangeLog
===================================================================
--- pkg/inst/ChangeLog	2008-08-28 07:46:24 UTC (rev 488)
+++ pkg/inst/ChangeLog	2008-08-28 10:39:42 UTC (rev 489)
@@ -21,6 +21,16 @@
 	environment as the general formula. Cures some tricky issues when
 	the partial term of cca/rda/capscale model is updated within a
 	function. (The environment() drives me crazy, says J.O.)
+
+	* ordiParseFormula gains new argument 'envdepth' to define the
+	depth where the community data (dependent data) is evaluated. Most
+	functions evaluate community data in the parent environment of the
+	calling function, but capscale() creates new dependent data and
+	needs evaluate the community within calling function. (The
+	environment() drives me absolutely crazy, says J.O.)
+
+	* vegan-internal.Rd: brief documentation of internal functions for
+	developers with some guidelines of good practices.
 	
 Version 1.14-9 (closed August 20, 2008)
 

Modified: pkg/man/vegan-internal.Rd
===================================================================
--- pkg/man/vegan-internal.Rd	2008-08-28 07:46:24 UTC (rev 488)
+++ pkg/man/vegan-internal.Rd	2008-08-28 10:39:42 UTC (rev 489)
@@ -10,11 +10,12 @@
 \title{Internal vegan functions}
 
 \description{
-  Internal vegan functions.
+  Internal vegan functions that are not intended to be called directly,
+  but only within other functions.
 }
 \usage{
 ordiGetData(call, env)
-ordiParseFormula(formula, data, xlev = NULL)
+ordiParseFormula(formula, data, xlev = NULL, envdepth = 2)
 ordiTerminfo(d, data)
 ordiArrowMul(x, at = c(0,0), fill = 0.75)
 ordiArgAbsorber(..., shrink, origin, scaling, triangular,
@@ -25,8 +26,41 @@
 }
 
 \details{
-  These are not to be called by the user. Function \code{ordispantree}
-  is deprecated: use \code{\link{lines.spantree}} instead.
+  The description here is only intended for \pkg{vegan} developers:
+  these functions are not intended for users, but they only should be
+  used within functions
+  
+  \code{ordiGetData} finds the model frame of constraints and conditions
+  in constrained ordination in the defined \code{env}ironment.
+  \code{ordiParseFormula} returns a list of three matrices (dependent
+  variables, and \code{\link{model.matrix}} of constraints and
+  conditions, possibly \code{NULL}) needed in constrained
+  ordination. Argument \code{xlev} is passed to
+  \code{\link{model.frame}} and argument \code{envdepth} specifies the
+  depth at which the community data (dependent data) is evaluated;
+  default \code{envdepth = 2} evaluates that in the environment of the
+  parent of the calling function, and \code{envdepth = 1} within the
+  calling function (see \code{\link{eval.parent}}). \code{ordiTermInfo}
+  finds the term information for constrained ordination as described in
+  \code{\link{cca.object}}.
+
+  \code{ordiArgAbsorber} absorbs arguments of \code{\link{scores}}
+  function of \pkg{vegan} so that these do not cause superfluous
+  warnings in graphical function \code{FUN}. If you implement
+  \code{scores} functions with new arguments, you should update
+  \code{ordiArgAbsorber}. 
+
+  \code{centroids.cca} finds the weighted centroids of variables.
+
+  \code{permuted.index} creates permuted index of length \code{n}
+  possibly stratified within \code{strata}. This is the basic \pkg{vegan}
+  permutation function that should be replaced with more powerful
+  \code{permuted.index2} in the future releases of \pkg{vegan}, and all
+  new functions should use \code{\link{permuted.index2}}.
+
+  \code{pasteCall} prints the function call so that it is nicely wrapped
+  in \code{\link[utils]{Sweave}} output.
+
 }
 
 \keyword{internal }