[Vegan-commits] r1347 - in pkg/vegan: R man

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

Author: jarioksa
Date: 2010-11-03 17:37:03 +0100 (Wed, 03 Nov 2010)
New Revision: 1347

Added:
   pkg/vegan/R/SSgitay.R
   pkg/vegan/R/SSlomolino.R
   pkg/vegan/man/SSarrhenius.Rd
Modified:
   pkg/vegan/man/specaccum.Rd
Log:
add hastily some self-starting species-area models (doc to follow)

Added: pkg/vegan/R/SSgitay.R
===================================================================
--- pkg/vegan/R/SSgitay.R	                        (rev 0)
+++ pkg/vegan/R/SSgitay.R	2010-11-03 16:37:03 UTC (rev 1347)
@@ -0,0 +1,10 @@
+SSgitay <-
+    selfStart(~ (k + slope*log(area))^2,
+              function(mCall, data, LHS)
+{
+    xy <- sortedXyData(mCall[["area"]], LHS, data)
+    value <- as.vector(coef(lm(sqrt(xy[,"y"]) ~ log(xy[,"x"]))))
+    names(value) <- mCall[c("k","slope")]
+    value
+},
+c("k","slope"))

Added: pkg/vegan/R/SSlomolino.R
===================================================================
--- pkg/vegan/R/SSlomolino.R	                        (rev 0)
+++ pkg/vegan/R/SSlomolino.R	2010-11-03 16:37:03 UTC (rev 1347)
@@ -0,0 +1,15 @@
+SSlomolino <-
+    selfStart(~ Asym/(1 + slope^log(xmid/area)),
+              function(mCall, data, LHS)
+{
+    xy <- sortedXyData(mCall[["area"]], LHS, data)
+    ## wild guess for starting values: assume Asym is 1.2*max(S), fit
+    ## log(S) ~ log(area), estimate xmid as area of that model giving
+    ## S/2 and assume slope is 1/slope of that model.
+    .S <- max(xy[,"y"])
+    .b <- as.vector(coef(lm(log(xy[,"y"]) ~ log(xy[,"x"]))))
+    value <- c(.S*1.2, exp(log(.S/2)/.b[2] - .b[1]), 1/.b[2])
+    names(value) <- mCall[c("Asym","xmid", "slope")]
+    value
+},
+c("Asym","xmid","slope"))

Added: pkg/vegan/man/SSarrhenius.Rd
===================================================================
--- pkg/vegan/man/SSarrhenius.Rd	                        (rev 0)
+++ pkg/vegan/man/SSarrhenius.Rd	2010-11-03 16:37:03 UTC (rev 1347)
@@ -0,0 +1,106 @@
+\name{SSarrhenius}
+\alias{SSarrhenius}
+\alias{SSlomolino}
+\alias{SSgitay}
+
+\title{
+  Self-Starting nls Species-Area Models
+}
+
+\description{
+  These functions provide self-starting species-area models for
+  non-linear regression (\code{\link{nls}}). They can also be used for
+  fitting species accumulation models in
+  \code{\link{fitspecaccum}}. These models (and many more) are reviewed
+  by Dengler (2009).
+}
+
+\usage{
+SSarrhenius(area, k, z)
+SSgitay(area, k, slope)
+SSlomolino(area, Asym, xmid, slope)
+}
+
+\arguments{
+  \item{area}{
+    Area or size of the sample: the independent variable.
+  }
+  \item{k, z, slope, Asym, xmid}{
+    Estimated model parameters: see Details.
+  }
+}
+\details{
+  All these functions are assumed to be used for species richness
+  (number of species) as the independent variable, and area or sample
+  size as the independent variable.
+
+  The Arrhenius model (\code{SSarrhenius}) is the expression
+  \code{k*area^z}. This is the most classical model that can be found in
+  any textbook of ecology (and also in Dengler 2009). Parameter \code{z}
+  is the steepness of the species-area curve, and \code{k} is the
+  expected number of species in a unit area.
+
+  The Gitay model (\code{SSgitay}) is a quadratic logarithmic expression
+  \code{(k + slope*log(area))^2} (Gitay et al. 1991, Dengler
+  2009). Parameter \code{slope} is the steepness of the species-area
+  curve, and \code{k} is the square root of expected richness in a unit
+  area. 
+
+  The Lomolino model (\code{SSlomolino}) is
+  \code{Asym/(1 + slope^log(xmid/area))} (Lomolino 2000, Dengler 2009).
+  Parameter \code{Asym} is the asymptotic maximum number of species,
+  \code{slope} is the maximum slope of increse of richness, and
+  \code{xmid} is the  area where half of the maximum richess is
+  achieved. 
+
+  In addition to these models, several other models studied by Dengler
+  (2009) are available in standard \R self-starting models:
+  Michaelis-Menten (\code{\link{SSmicmen}}), Gompertz
+  (\code{\link{SSgompertz}}), logistic (\code{\link{SSlogis}}), Weibull
+  (\code{\link{SSweibull}}), and some others that may be useful.
+    
+}
+\value{
+  Numeric vector of the same length as \code{area}. It is the value of
+  the expression of each model. If all arguments are names of objects
+  the gradient matrix with respect to these names is attached as an
+  attribute named \code{gradient}. 
+}
+\references{
+  Dengler, J. (2009) Which function describes the species-area
+  relationship best? A review and empirical evaluation. \emph{Journal of
+    Biogeography} 36, 728--744.
+
+  Gitay, H., Roxburgh, S.H. & Wilson, J.B. (1991) Species-area
+  relationship in a New Zealand tussock grassland, with implications for
+  nature reserve design and for community structure. \emph{Journal of
+  Vegetation Science} 2, 113--118.
+
+  Lomolino, M. V. (2000) Ecology's most general, yet protean pattern:
+  the species-area relationship. \emph{Journal of Biogeography} 27,
+  17--26. 
+}
+\author{
+  Jari Oksanen.
+}
+
+\seealso{
+  \code{\link{nls}}, \code{\link{fitspecaccum}}. 
+}
+\examples{
+## Get species area data: sipoo.area gives the areas of islands
+example(sipoo)
+S <- specnumber(sipoo)
+plot(S ~ sipoo.area, xlab = "Island Area (ha)", ylab = "Number of Species")
+## The Arrhenius model
+marr <- nls(S ~ SSarrhenius(sipoo.area, k, z))
+marr
+## confidence limits from profile likelihood
+confint(marr)
+## draw a line
+xtmp <- seq(min(sipoo.area), max(sipoo.area), len=51)
+lines(xtmp, predict(marr, newdata=data.frame(sipoo.area = xtmp)), lwd=2)
+## The normal way is to use linear regression on double log data.
+}
+\keyword{ models }
+

Modified: pkg/vegan/man/specaccum.Rd
===================================================================
--- pkg/vegan/man/specaccum.Rd	2010-11-03 09:10:05 UTC (rev 1346)
+++ pkg/vegan/man/specaccum.Rd	2010-11-03 16:37:03 UTC (rev 1347)
@@ -5,7 +5,6 @@
 \alias{plot.specaccum}
 \alias{boxplot.specaccum}
 \alias{fitspecaccum}
-\alias{SSarrhenius}
 
 \title{Species Accumulation Curves }
 \description{