[Vegan-commits] r2298 - pkg/vegan/man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed Sep 26 20:47:22 CEST 2012
Author: jarioksa
Date: 2012-09-26 20:47:22 +0200 (Wed, 26 Sep 2012)
New Revision: 2298
Modified:
pkg/vegan/man/radfit.Rd
Log:
restructure and update radfit documentation
Modified: pkg/vegan/man/radfit.Rd
===================================================================
--- pkg/vegan/man/radfit.Rd 2012-09-26 13:40:10 UTC (rev 2297)
+++ pkg/vegan/man/radfit.Rd 2012-09-26 18:47:22 UTC (rev 2298)
@@ -3,17 +3,25 @@
\alias{radfit.default}
\alias{radfit.data.frame}
\alias{AIC.radfit}
+\alias{AIC.radfit.frame}
\alias{as.rad}
\alias{coef.radfit}
+\alias{coef.radfit.frame}
+\alias{deviance.radfit}
+\alias{deviance.radfit.frame}
+\alias{logLik, radfit}
+\alias{logLik, radfit.frame}
\alias{fitted.radfit}
\alias{fitted.radfit.frame}
\alias{lines.radline}
+\alias{lines.radfit}
\alias{plot.radfit.frame}
\alias{plot.radfit}
\alias{plot.radline}
\alias{plot.rad}
\alias{radlattice}
\alias{points.radline}
+\alias{points.radfit}
\alias{summary.radfit.frame}
\alias{rad.preempt}
\alias{rad.lognormal}
@@ -32,18 +40,19 @@
}
\usage{
\method{radfit}{default}(x, ...)
-\method{plot}{radfit.frame}(x, order.by, BIC = FALSE, model, legend = TRUE,
- as.table = TRUE, ...)
-\method{plot}{radfit}(x, BIC = FALSE, legend = TRUE, ...)
-radlattice(x, BIC = FALSE, ...)
rad.null(x, family=poisson, ...)
rad.preempt(x, family = poisson, ...)
rad.lognormal(x, family = poisson, ...)
rad.zipf(x, family = poisson, ...)
rad.zipfbrot(x, family = poisson, ...)
+\method{predict}{radline}(object, newdata, total, ...)
+\method{plot}{radfit}(x, BIC = FALSE, legend = TRUE, ...)
+\method{plot}{radfit.frame}(x, order.by, BIC = FALSE, model, legend = TRUE,
+ as.table = TRUE, ...)
\method{plot}{radline}(x, xlab = "Rank", ylab = "Abundance", type = "b", ...)
-\method{lines}{radline}(x, ...)
-\method{points}{radline}(x, ...)
+radlattice(x, BIC = FALSE, ...)
+\method{lines}{radfit}(x, ...)
+\method{points}{radfit}(x, ...)
as.rad(x)
\method{plot}{rad}(x, xlab = "Rank", ylab = "Abundance", log = "y", ...)
}
@@ -51,6 +60,20 @@
\arguments{
\item{x}{Data frame, matrix or a vector giving species abundances, or an object to
be plotted.}
+
+ \item{family}{Error distribution (passed to \code{\link{glm}}). All
+ alternatives accepting \code{link = "log"} in \code{\link{family}}
+ can be used, although not all make sense.}
+
+ \item{object}{A fitted result object.}
+
+ \item{newdata}{Ranks used for ordinations. All models can
+ interpolate to non-integer \dQuote{ranks} (although this may be
+ approximate), but extrapolation may fail}
+
+ \item{total}{The new total used for predicting abundance. Observed
+ total count is used if this is omitted.}
+
\item{order.by}{A vector used for ordering sites in plots.}
\item{BIC}{Use Bayesian Information Criterion, BIC, instead of
Akaike's AIC. The penalty for a parameter is \eqn{k = \log(S)}{k =
@@ -63,9 +86,6 @@
\item{legend}{Add legend of line colours.}
\item{as.table}{Arrange panels starting from upper left corner (passed
to \code{\link[lattice]{xyplot}}).}
- \item{family}{Error distribution (passed to \code{\link{glm}}). All
- alternatives accepting \code{link = "log"} in \code{\link{family}}
- can be used, although not all make sense.}
\item{xlab,ylab}{Labels for \code{x} and \code{y} axes.}
\item{type}{Type of the plot, \code{"b"} for plotting both observed points
and fitted lines, \code{"p"} for only points, \code{"l"} for only
@@ -78,102 +98,112 @@
\item{\dots}{Other parameters to functions. }
}
\details{
- Rank -- Abundance Dominance (RAD) or Dominance/Diversity plots
+
+ Rank--Abundance Dominance (RAD) or Dominance/Diversity plots
(Whittaker 1965) display logarithmic species abundances against
- species rank order. These plots are supposed to be
- effective in analysing types of abundance distributions in
- communities. These functions fit some of the most popular models mainly
- following Wilson (1991). Function \code{as.rad} constructs observed
- RAD data.
- Functions \code{rad.XXXX} (where \code{XXXX} is a name) fit
- the individual models, and
- function \code{radfit} fits all models. The
+ species rank order. These plots are supposed to be effective in
+ analysing types of abundance distributions in communities. These
+ functions fit some of the most popular models mainly following
+ Wilson (1991).
+
+ Functions \code{rad.null}, \code{rad.preempt}, \code{rad.lognormal},
+ \code{rad.zipf} and \code{zipfbrot} fit the individual models
+ (described below), and function \code{radfit} fits all models. The
argument of the function \code{radfit} can be either a vector for a
single community or a data frame where each row represents a
- distinct community. All these functions have their own \code{plot}
- functions. When the argument is a data frame, \code{plot} uses
- \code{\link[lattice]{Lattice}} graphics, and other \code{plot} functions use
- ordinary graphics. The ordinary graphics functions return invisibly an
- \code{\link{ordiplot}} object for observed points, and function
- \code{\link{identify.ordiplot}} can be used to label selected
- species. The most complete control of graphics can be achieved
- with \code{rad.XXXX} methods which have \code{points} and \code{lines}
- functions to add observed values and fitted models into existing
- graphs. Alternatively, \code{radlattice} uses
- \code{\link[lattice]{Lattice}} graphics to display each
- \code{radfit} model in a separate panel together with their AIC or
- BIC values.
+ distinct community. There are grand narratives about ecological
+ mechanisms behind each model (Wilson 1991), but several alternative
+ and contrasting mechanisms can produce similar models and a good fit
+ does not imply a specific mechanism.
Function \code{rad.null} fits a brokenstick model where the expected
- abundance of species at rank \eqn{r} is \eqn{a_r = (J/S) \sum_{x=r}^S
- (1/x)}{a[r] = J/S sum(from x=r to S) 1/x} (Pielou 1975), where \eqn{J}
- is the total number of individuals (site total) and \eqn{S} is the
- total number of species in the community. This gives a Null model
- where the individuals are randomly distributed among observed species,
- and there are no fitted parameters.
+ abundance of species at rank \eqn{r} is \eqn{a_r = (J/S)
+ \sum_{x=r}^S (1/x)}{a[r] = J/S sum(from x=r to S) 1/x} (Pielou
+ 1975), where \eqn{J} is the total number of individuals (site total)
+ and \eqn{S} is the total number of species in the community. This
+ gives a Null model where the individuals are randomly distributed
+ among observed species, and there are no fitted parameters.
Function \code{rad.preempt} fits the niche preemption model,
a.k.a. geometric series or Motomura model, where the expected
- abundance \eqn{a} of species at rank \eqn{r} is \eqn{a_r = J \alpha (1 -
- \alpha)^{r-1}}{a[r] = J*alpha*(1-alpha)^(r-1)}. The only estimated
- parameter is the preemption coefficient \eqn{\alpha} which gives the
- decay rate of abundance per rank.
- The niche preemption model is a straight line in a
- RAD plot. Function \code{rad.lognormal} fits a log-Normal model which
- assumes that the logarithmic abundances are distributed Normally, or
- \eqn{a_r = \exp( \log \mu + \log \sigma N)}{a[r] = exp(log(mu) +
- log(sigma) * N)}, where \eqn{N} is a Normal deviate.
- Function \code{rad.zipf} fits the Zipf model \eqn{a_r = J p_1
- r^\gamma}{a[r] = J*p1*r^gamma} where \eqn{p_1}{p1} is the fitted
- proportion of the most abundant species, and \eqn{\gamma} is a
- decay coefficient. The
- Zipf -- Mandelbrot
- model (\code{rad.zipfbrot}) adds one parameter: \eqn{a_r = J c
- (r + \beta)^\gamma}{a[r] = J*c*(r+beta)^gamma} after which
- \eqn{p_1}{p1} of the Zipf model changes into a meaningless scaling
- constant \eqn{c}. There are grand narratives about ecological
- mechanisms behind each model (Wilson 1991), but
- several alternative and contrasting mechanisms can produce
- similar models and a good fit does not imply a specific mechanism.
+ abundance \eqn{a} of species at rank \eqn{r} is \eqn{a_r = J \alpha
+ (1 - \alpha)^{r-1}}{a[r] = J*alpha*(1-alpha)^(r-1)}. The only
+ estimated parameter is the preemption coefficient \eqn{\alpha} which
+ gives the decay rate of abundance per rank. The niche preemption
+ model is a straight line in a RAD plot. Function
+ \code{rad.lognormal} fits a log-Normal model which assumes that the
+ logarithmic abundances are distributed Normally, or \eqn{a_r = \exp(
+ \log \mu + \log \sigma N)}{a[r] = exp(log(mu) + log(sigma) * N)},
+ where \eqn{N} is a Normal deviate. Function \code{rad.zipf} fits
+ the Zipf model \eqn{a_r = J p_1 r^\gamma}{a[r] = J*p1*r^gamma} where
+ \eqn{p_1}{p1} is the fitted proportion of the most abundant species,
+ and \eqn{\gamma} is a decay coefficient. The Zipf--Mandelbrot model
+ (\code{rad.zipfbrot}) adds one parameter: \eqn{a_r = J c (r +
+ \beta)^\gamma}{a[r] = J*c*(r+beta)^gamma} after which \eqn{p_1}{p1}
+ of the Zipf model changes into a meaningless scaling constant
+ \eqn{c}.
Log-Normal and Zipf models are generalized linear models
- (\code{\link{glm}}) with logarithmic link function. Zipf-Mandelbrot
+ (\code{\link{glm}}) with logarithmic link function. Zipf--Mandelbrot
adds one nonlinear parameter to the Zipf model, and is fitted using
\code{\link{nlm}} for the nonlinear parameter and estimating other
- parameters and log-Likelihood with \code{\link{glm}}. Pre-emption
+ parameters and log-Likelihood with \code{\link{glm}}. Preemption
model is fitted as purely nonlinear model. There are no estimated
- parameters in the Null model. The default \code{\link{family}} is
- \code{poisson} which is appropriate only for genuine counts
- (integers), but other families that accept \code{link = "log"} can
- be used. Family \code{\link{Gamma}} may be appropriate for abundance
- data, such as cover. The ``best'' model is selected by
+ parameters in the Null model.
+
+ The default \code{\link{family}} is \code{poisson} which is
+ appropriate only for genuine counts (integers), but other families
+ that accept \code{link = "log"} can be used. Families
+ \code{\link{Gamma}} or \code{\link{gaussian}} may be appropriate for
+ abundance data, such as cover. The ``best'' model is selected by
\code{\link{AIC}}. Therefore ``quasi'' families such as
\code{\link{quasipoisson}} cannot be used: they do not have
\code{\link{AIC}} nor log-Likelihood needed in non-linear models.
+
+ All these functions have their own \code{plot} functions. When the
+ argument is a data frame, \code{plot} uses
+ \code{\link[lattice]{Lattice}} graphics, and other \code{plot}
+ functions use ordinary graphics. The ordinary graphics functions
+ return invisibly an \code{\link{ordiplot}} object for observed
+ points, and function \code{\link{identify.ordiplot}} can be used to
+ label selected species. Alternatively, \code{radlattice} uses
+ \code{\link[lattice]{Lattice}} graphics to display each
+ \code{radfit} model in a separate panel together with their AIC or
+ BIC values.
+ Function \code{as.rad} is a base function to construct ordered RAD
+ data. Its \code{plot} is used by other RAD \code{plot} functions
+ which pass extra arguments (such as \code{xlab} and \code{log}) to
+ this function.
+
}
\value{
- Function \code{rad.XXXX} will return an object of class
- \code{radline}, which is constructed to resemble results of \code{\link{glm}}
- and has many (but not all) of its components, even when only
- \code{\link{nlm}} was used in fitting. At least the following
- \code{\link{glm}} methods can be applied to the result:
- \code{\link{fitted}}, \code{\link{residuals.glm}} with alternatives
- \code{"deviance"} (default), \code{"pearson"}, \code{"response"},
- function \code{\link{coef}}, \code{\link{AIC}},
- \code{\link{extractAIC}}, and \code{\link{deviance}}.
- Function \code{radfit} applied to a vector will return
- an object of class \code{radfit} with item \code{y} for the
- constructed RAD, item \code{family} for the error distribution, and
- item \code{models} containing each \code{radline} object as an
- item. In addition, there are special \code{AIC}, \code{coef} and
- \code{fitted} implementations for \code{radfit} results.
- When applied to a data frame
- \code{radfit} will return an object of class \code{radfit.frame} which
- is a list of \code{radfit} objects; function \code{summary} can be
- used to display the results for individual \code{radfit} objects.
- The functions are still
- preliminary, and the items in the \code{radline} objects may change.
+
+ Functions \code{rad.null}, \code{rad.preempt}, \code{rad.lognormal},
+ \code{zipf} and \code{zipfbrot} fit each a single RAD model to a
+ single site. The result object has class \code{"radline"} and
+ inherits from \code{\link{glm}}, and can be handled by some (but not
+ all) \code{\link{glm}} methods.
+
+ Function \code{radfit} fits all models either to a single site or to
+ all rows of a data frame or a matrix. When fitted to a single site,
+ the function returns an object of class \code{"radfit"} which
+ returns items \code{y} (observed values), \code{\link{family}}, and
+ \code{models} which is a list of fitted \code{"radline"} models.
+ When applied for a data frame or matrix, \code{radfit} function
+ returns an object of class \code{"radfit.frame"} which is a list of
+ \code{"radfit"} objects, each item names by the corresponding row
+ name.
+
+ All result objects (\code{"radline"}, \code{"radfit"},
+ \code{"radfit.frame"}) can be accessed with same method functions.
+ The following methods are available: \code{\link{AIC}},
+ \code{\link{coef}}, \code{\link{deviance}}, \code{\link{logLik}}. In
+ addition the fit results can be accessed with \code{\link{fitted}},
+ \code{\link{predict}} and \code{\link{residuals}} (inheriting from
+ \code{\link{residuals.glm}}).The graphical functions were discussed
+ above in Details.
+
}
\references{
More information about the Vegan-commits
mailing list