[Vegan-commits] r2493 - in pkg/vegan: R man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sun Apr 21 04:05:45 CEST 2013
Author: gsimpson
Date: 2013-04-21 04:05:40 +0200 (Sun, 21 Apr 2013)
New Revision: 2493
Modified:
pkg/vegan/R/ordisurf.R
pkg/vegan/man/ordisurf.Rd
Log:
some of the bases don't work in 2-D 's()' smooths; 'fx = TRUE' and 'select = TRUE' are not compatible; updated all examples to reflect new defaults and options; updated the help page significantly with new notes, warnings etc.
Modified: pkg/vegan/R/ordisurf.R
===================================================================
--- pkg/vegan/R/ordisurf.R 2013-04-20 21:28:47 UTC (rev 2492)
+++ pkg/vegan/R/ordisurf.R 2013-04-21 02:05:40 UTC (rev 2493)
@@ -46,16 +46,27 @@
}
x1 <- X[, 1]
x2 <- X[, 2]
+ ## handle fx - allow vector of length up to two
+ if(!(missfx <- missing(fx)) && missing(knots))
+ warning("Requested fixed d.f. splines but without specifying 'knots'.\nSwitching to 'fx = FALSE'.")
+ if (length(fx) > 2L)
+ warning("Length of 'fx' supplied exceeds '2'. Using the first two.")
+ ## expand fx robustly, no matter what length supplied
+ fx <- rep(fx, length.out = 2)
+ ## can't have `fx = TRUE` and `select = TRUE`
+ if(!missfx) { ## fx set by user
+ if((miss.select <- missing(select)) && any(fx)) {
+ warning("'fx = TRUE' requested; using 'select = FALSE'")
+ select <- FALSE
+ } else if(!miss.select && isTRUE(select)){
+ stop("Fixed d.f. splines ('fx = TRUE') incompatible with 'select = TRUE'")
+ }
+ }
## handle knots - allow vector of length up to two
if (length(knots) > 2L)
warning("Length of 'knots' supplied exceeds '2'. Using the first two.")
## expand knots robustly, no matter what length supplied
knots <- rep(knots, length.out = 2)
- ## handle fx - allow vector of length up to two
- if (length(fx) > 2L)
- warning("Length of 'fx' supplied exceeds '2'. Using the first two.")
- ## expand fx robustly, no matter what length supplied
- fx <- rep(fx, length.out = 2)
## handle the bs - we only allow some of the possible options
if (length(bs) > 2L)
warning("Number of basis types supplied exceeds '2'. Only using the first two.")
@@ -70,6 +81,10 @@
paste(sQuote(unique(user.bs[wrong])), collapse = ", "),
"not supported."))
}
+ ## can't use "cr", "cs", "ps" in 2-d smoother with s()
+ if(isTRUE(isotropic) && any(bs %in% c("cr", "cs", "ps"))) {
+ stop("Bases \"cr\", \"cs\", and \"ps\" not allowed in isotropic smooths.")
+ }
## Build formula
if (knots[1] <= 0) {
f <- formula(y ~ x1 + x2)
Modified: pkg/vegan/man/ordisurf.Rd
===================================================================
--- pkg/vegan/man/ordisurf.Rd 2013-04-20 21:28:47 UTC (rev 2492)
+++ pkg/vegan/man/ordisurf.Rd 2013-04-21 02:05:40 UTC (rev 2493)
@@ -31,9 +31,10 @@
\arguments{
\item{x}{For \code{ordisurf} an ordination configuration, either a
matrix or a result known by \code{\link{scores}}. For
- \code{plot.ordisurf} and object of class \code{"ordisurf"} as
+ \code{plot.ordisurf} an object of class \code{"ordisurf"} as
returned by \code{ordisurf}.}
- \item{y}{ Variable to be plotted. }
+ \item{y}{Variable to be plotted / modelled as a function of the
+ ordination scores.}
\item{choices}{Ordination axes. }
\item{knots}{Number of initial knots in \code{\link[mgcv]{gam}} (one
more than degrees of freedom). If \code{knots = 0} or
@@ -41,8 +42,8 @@
if \code{knots = 2} the function will fit a quadratic trend surface
instead of a smooth surface. A vector of length 2 is allowed when
\code{isotropic = FALSE}, with the first and second elements of
- \code{knots} refering to the first and second of the ordination
- dimensions indicated by \code{choices}.}
+ \code{knots} refering to the first and second of ordination
+ dimensions (as indicated by \code{choices}) respectively.}
\item{family}{Error distribution in \code{\link[mgcv]{gam}}.}
\item{col}{ Colour of contours. }
\item{isotropic, thinplate}{Fit an isotropic smooth surface (i.e. same
@@ -54,12 +55,16 @@
\code{"cr"} for cubic regression spline). One of \code{c("tp", "ts",
"cr", "cs", "ds", "ps", "ad")}. See
\code{\link[mgcv]{smooth.terms}} for an over view of what these
- refer to. The default is to use thin plate splines \code{"tp"}.}
+ refer to. The default is to use thin plate splines: \code{bs = "tp"}.}
\item{fx}{indicates whether the smoothers are fixed degree of freedom
regression splines (\code{fx = FALSE}) or penalised regression
splines (\code{fx = TRUE}). Can be a vector of length 2 for
- anisotropic surfaces (\code{isotropic = FALSE}).}
- \item{add}{Add contours to an existing diagram or draw a new plot.}
+ anisotropic surfaces (\code{isotropic = FALSE}). It doesn't make
+ sense to use \code{fx = TRUE} \strong{and} \code{select = TRUE} and
+ it is an \strong{error} to do so. A warning is issued if you specify
+ \code{fx = TRUE} and forget to use \code{select = FALSE} though
+ fitting continues using \code{select = FALSE}.}
+ \item{add}{Add contours to an existing diagram or draw a new plot?}
\item{display}{Type of scores known by \code{\link{scores}}: typically
"sites" for ordinary site scores or "lc" for linear combination scores.}
\item{w}{Prior weights on the data. Concerns mainly \code{\link{cca}}
@@ -74,7 +79,7 @@
dimension.}
\item{labcex}{Label size in contours. Setting this zero will suppress
labels.}
- \item{bubble}{Use \dQuote{bubble plot} for points, or vary the point
+ \item{bubble}{Use a \dQuote{bubble plot} for points, or vary the point
diameter by the value of the plotted variable. If \code{bubble} is
numeric, its value is used for the maximum symbol size (as in
\code{cex}), or if \code{bubble = TRUE}, the value of \code{cex} gives
@@ -99,7 +104,7 @@
of the scale.}
\item{gamma}{Multiplier to inflate model degrees of freedom in GCV or
UBRE/AIC score by. This effectively places an extra penalty on
- complex models. An oft used value if \code{gamma = 1.4}.}
+ complex models. An oft-used value is \code{gamma = 1.4}.}
\item{plot}{logical; should any plotting be done by
\code{ordisurf}? Useful if all you want is the fitted response
surface model.}
@@ -119,7 +124,7 @@
details. \code{"gam"} plots the fitted GAM model, an object that
inherits from class \code{"gam"} returned by \code{ordisurf}, see
\code{\link[mgcv]{plot.gam}}.}
- \item{\dots}{Other parameters passed to \code{\link[mgcv]{gam}}, or
+ \item{\dots}{Other parameters passed to \code{\link{scores}}, or
to the graphical functions. See Note below for exceptions.}
}
@@ -136,18 +141,24 @@
use a spline basis that includes shrinkage (\code{bs = "ts"} or
\code{bs = "cs"}).
+ \code{ordisurf()} exposes a large number of options from
+ \code{\link[mgcv]{gam}} for specifying the basis functions used for
+ the surface. If you stray from the defaults, do read the
+ \strong{Notes} section below and relevant documentation in
+ \code{\link[mgcv]{s}} and \code{\link[mgcv]{smooth.terms}}.
+
The function plots the fitted contours with convex hull of data points
either over an existing ordination diagram or draws a new plot. If
\code{select = TRUE} and the smooth is effectively penalised out of
the model, no contours will be plotted.
\code{\link[mgcv]{gam}} determines the degree of smoothness for the
- fitted response surface during model fitting. Argument \code{method}
- controls how \code{\link[mgcv]{gam}} performs this smoothness
- selection. See \code{\link[mgcv]{gam}} for details of the available
- options. Using \code{"REML"} or \code{"ML"} yields p-values for
- smooths with the best coverage properties if such things matter to
- you.
+ fitted response surface during model fitting, unless \code{fx =
+ TRUE}. Argument \code{method} controls how \code{\link[mgcv]{gam}}
+ performs this smoothness selection. See \code{\link[mgcv]{gam}} for
+ details of the available options. Using \code{"REML"} or \code{"ML"}
+ yields p-values for smooths with the best coverage properties if such
+ things matter to you.
The function uses \code{\link{scores}} to extract ordination scores,
and \code{x} can be any result object known by that function.
@@ -169,17 +180,18 @@
}
\value{
- Function is usually called for its side effect of drawing the
- contour plot. The function returns the result object of class
+ \code{ordisurf} is usually called for its side effect of drawing the
+ contour plot. The function returns a result object of class
\code{"ordisurf"} that inherits from \code{\link[mgcv]{gam}} used
internally to fit the surface, but adds an item \code{grid} that
contains the data for the grid surface. The item \code{grid} has
elements \code{x} and \code{y} which are vectors of axis coordinates,
and element \code{z} that is a matrix of fitted values for
\code{\link{contour}}. The values outside the convex hull of observed
- points are \code{NA} in \code{z}. The \code{\link[mgcv]{gam}}
- component of the result can be used for further analysis like
- predicting new values (see \code{\link[mgcv]{predict.gam}}).
+ points are indicated as \code{NA} in \code{z}. The
+ \code{\link[mgcv]{gam}} component of the result can be used for
+ further analysis like predicting new values (see
+ \code{\link[mgcv]{predict.gam}}).
}
\author{ Dave Roberts, Jari Oksanen and Gavin L. Simpson }
@@ -188,18 +200,26 @@
\code{\link[mgcv]{s}} employing thin plate regression splines
(\code{bs = "tp"}). These make sense in ordination as they have
equal smoothing in all directions and are rotation invariant. However,
- if different degrees of smoothness along one dimension, an anisotropic
- smooth surface may be more applicable. This can be achieved through
- the use of \code{isotropic = FALSE}, wherein the surface is fitted via
- a tensor product smoother via \code{\link[mgcv]{te}} (unless \code{bs
- = "ad"}, in which case separate splines for each dimension are
- fitted using \code{\link[mgcv]{s}}).
+ if different degrees of smoothness along dimensions are required, an
+ anisotropic smooth surface may be more applicable. This can be
+ achieved through the use of \code{isotropic = FALSE}, wherein the
+ surface is fitted via a tensor product smoother via
+ \code{\link[mgcv]{te}} (unless \code{bs = "ad"}, in which case
+ separate splines for each dimension are fitted using
+ \code{\link[mgcv]{s}}).
+ Cubic regression splines and P splines can \strong{only} be used with
+ \code{isotropic = FALSE}.
+
Adaptive smooths (\code{bs = "ad"}), especially in two dimensions,
require a large number of observations; without many hundreds of
observations, the default complexities for the smoother will exceed
the number of observations and fitting will fail.
+ To get the old behaviour of \code{ordisurf} use \code{select = FALSE},
+ \code{method = "GCV.Cp"}, \code{fx = FALSE}, and \code{bs = "tp"}. The
+ latter two options are the current defaults.
+
Graphical arguments supplied to \code{plot.ordisurf} are passed on to
the underlying plotting functions, \code{contour}, \code{persp}, and
\code{\link[mgcv]{plot.gam}}. The exception to this is that arguments
@@ -212,6 +232,20 @@
illustration of this.
}
+\section{Warning}{
+ The fitted GAM is a regression model and has the usual assumptions of
+ such models. Of particular note is the assumption of independence of
+ residuals. If the observations are not independent (e.g. they are
+ repeat measures on a set of objects, or from an experimental design,
+ \emph{inter alia}) do not trust the \emph{p}-values from the GAM
+ output.
+
+ If you need further control (i.e. to add additional fixed effects to
+ the model, or use more complex smoothers), extract the ordination
+ scores using the \code{scores} function and then generate your own
+ \code{\link[mgcv]{gam}} call.
+}
+
\references{
Marra, G.P & Wood, S.N. (2011) Practical variable selection for
@@ -235,15 +269,28 @@
vare.mds <- monoMDS(vare.dist)
with(varechem, ordisurf(vare.mds, Baresoil, bubble = 5))
-## as above but with extra penalties on smooth terms:
-with(varechem, ordisurf(vare.mds, Baresoil, bubble = 5, col = "blue",
- add = TRUE, select = TRUE))
+## as above but without the extra penalties on smooth terms,
+## and using GCV smoothness selection (old behaviour of `ordisurf()`):
+with(varechem, ordisurf(vare.mds, Baresoil,col = "blue", add = TRUE,
+ select = FALSE, method = "GCV.Cp"))
## Cover of Cladina arbuscula
fit <- with(varespec, ordisurf(vare.mds, Cla.arb, family=quasipoisson))
## Get fitted values
calibrate(fit)
+## Variable selection via additional shrinkage penalties
+## This allows non-significant smooths to be selected out
+## of the model not just to a linear surface. There are 2
+## options available:
+## - option 1: `select = TRUE` --- the *default*
+with(varechem,
+ ordisurf(vare.mds, Baresoil, method = "REML", select = TRUE))
+## - option 2: use a basis with shrinkage
+with(varechem,
+ ordisurf(vare.mds, Baresoil, method = "REML", bs = "ts"))
+## or bs = "cs" with `isotropic = FALSE`
+
## Plot method
plot(fit, what = "contour")
@@ -253,17 +300,24 @@
plot.gam(fit, cex = 2, pch = 1, col = "blue")
## 'col' effects all objects drawn...
-## Variable selection via additional shrinkage penalties
-## This allows non-significant smooths to be selected out
-## of the model not just to a linear surface. There are 2
-## options available:
-## - option 1: `select = TRUE`
-with(varechem,
- ordisurf(vare.mds, Baresoil, method = "REML", select = TRUE))
-## - option 2: use a basis with shrinkage
-with(varechem,
- ordisurf(vare.mds, Baresoil, method = "REML", bs = "ts"))
-## or bs = "cs"
+### controlling the basis functions used
+## Use Duchon splines
+with(varechem, ordisurf(vare.mds, Baresoil, bs = "ds"))
+
+## A fixed degrees of freedom smooth, must use 'select = FALSE'
+with(varechem, ordisurf(vare.mds, Baresoil, knots = 4,
+ fx = TRUE, select = FALSE))
+
+## An anisotropic smoother with cubic regression spline bases
+with(varechem, ordisurf(vare.mds, Baresoil, isotropic = FALSE,
+ bs = "cr", knots = 4))
+
+## An anisotropic smoother with cubic regression spline with
+## shrinkage bases & different degrees of freedom in each dimension
+with(varechem, ordisurf(vare.mds, Baresoil, isotropic = FALSE,
+ bs = "cs", knots = c(3,4), fx = TRUE,
+ select = FALSE))
+
}
\keyword{ multivariate }
\keyword{ aplot }
More information about the Vegan-commits
mailing list