[Vegan-commits] r487 - in pkg: inst man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed Aug 27 14:49:07 CEST 2008
Author: jarioksa
Date: 2008-08-27 14:49:07 +0200 (Wed, 27 Aug 2008)
New Revision: 487
Added:
pkg/man/nestedtemp.Rd
Modified:
pkg/inst/ChangeLog
pkg/man/oecosimu.Rd
Log:
split docs of oecosimu and nestedness indices
Modified: pkg/inst/ChangeLog
===================================================================
--- pkg/inst/ChangeLog 2008-08-27 09:31:33 UTC (rev 486)
+++ pkg/inst/ChangeLog 2008-08-27 12:49:07 UTC (rev 487)
@@ -14,6 +14,8 @@
define the name of the statistic in the function call. This means
that things like functional diversity (treedive) for sites can be
analysed with approprite simulation model.
+
+ * nestedtemp & oecosimu documentations split.
* ordiParseFormula: formula of the partial terms has the same
environment as the general formula. Cures some tricky issues when
Copied: pkg/man/nestedtemp.Rd (from rev 486, pkg/man/oecosimu.Rd)
===================================================================
--- pkg/man/nestedtemp.Rd (rev 0)
+++ pkg/man/nestedtemp.Rd 2008-08-27 12:49:07 UTC (rev 487)
@@ -0,0 +1,127 @@
+\encoding{UTF-8}
+\name{nestedtemp}
+\alias{nestedtemp}
+\alias{nestedchecker}
+\alias{nestedn0}
+\alias{nesteddisc}
+\alias{print.nestedchecker}
+\alias{print.nestedn0}
+\alias{print.nesteddisc}
+\alias{print.nestedtemp}
+\alias{plot.nestedtemp}
+
+\title{ Nestedness Indices for Communities of Islands or Patches }
+
+\description{
+ Patches or local communities are regarded as nested if they all could
+ be subsets of the same community. In general, species poor communities
+ should be subsets of species rich communities, and rare species should
+ only occur in species rich communities.
+}
+
+\usage{
+nestedchecker(comm)
+nestedn0(comm)
+nesteddisc(comm)
+nestedtemp(comm, ...)
+\method{plot}{nestedtemp}(x, kind = c("temperature", "incidendce"),
+ col=rev(heat.colors(100)), names = FALSE, ...)
+}
+
+\arguments{
+ \item{comm}{Community data. }
+ \item{x}{Result object for a \code{plot}.}
+ \item{col}{Colour scheme for matrix temperatures.}
+ \item{kind}{The kind of plot produced.}
+ \item{names}{Label columns and rows in the plot using names in \code{comm}.}
+ \item{\dots}{Other arguments to functions.}
+}
+
+\details{
+ The nestedness functions evaluate alternative indices of nestedness.
+ The functions are intended to be used together with Null model
+ communities and used as an argument in \code{\link{oecosimu}} to analyse
+ the nonrdanomness of results.
+
+ Function \code{netstedchecker} gives the number of checkerboard units,
+ or 2x2 submatrices where both species occur once but on different
+ sites (Stone & Roberts 1990). Function \code{nestedn0} implements
+ nestedness measure N0 which is the number of absences from the sites
+ which are richer than the most pauperate site species occurs
+ (Patterson & Atmar 1986). Function \code{nesteddisc} implements
+ discrepancy index which is the number of ones that should be shifted
+ to fill a row with ones in a table arranged by species frequencies
+ (Brualdi & Sanderson 1999). Function \code{nestedtemp} finds the
+ matrix temperature which is defined as the sum of \dQuote{surprises}
+ in arranged matrix. In arranged unsurprising matrix all species
+ within proportion given by matrix fill are in the upper left corner of
+ the matrix, and the surprise of the absence or presences is the
+ diagonal distance from the fill line (Atmar & Patterson
+ 1993). Function tries to pack species and sites to a low
+ temperature (\enc{Rodríguez-Gironés}{Rodriguez-Girones} & Santamaria
+ 2006), but this is an iterative procedure, and the temperatures
+ usually vary among runs. Function \code{nestedtemp} also has a
+ \code{plot} method which can display either incidences or temperatures
+ of the surprises. Matrix temperature was rather vaguely described
+ (Atmar & Patterson 1993), but
+ \enc{Rodríguez-Gironés}{Rodriguez-Girones} & Santamaria (2006) are
+ more explicit and their description is used here. However, the results
+ probably differ from other implementations, and users should be
+ cautious in interpreting the results. The details of calculations
+ are explained in the \code{\link{vignette}} \emph{Design decisions
+ and implementation} that you can read using functions
+ \code{\link{vignette}} or \code{\link{vegandocs}}.
+}
+
+\value{
+ The result returned by a nestedness function contains an item called
+ \code{statistic}, but the other components differ among functions. The
+ functions are constructed so that they can be handled by
+ \code{\link{oecosimu}}.
+}
+
+\references{
+ Atmar, W. & Patterson, B.D. (1993). The measurement of order and
+ disorder in the distribution of species in fragmented
+ habitat. \emph{Oecologia} 96, 373--382.
+
+ Brualdi, R.A. & Sanderson, J.G. (1999). Nested species subsets, gaps,
+ and discrepancy. \emph{Oecologia} 119, 256--264.
+
+ Patterson, B.D. & Atmar, W. (1986). Nested subsets and the structure
+ of insular mammalian faunas and archipelagos. \emph{Biol. J. Linnean
+ Soc.} 28, 65--82.
+
+ \enc{Rodríguez-Gironés}{Rodriguez-Girones}, M.A. & Santamaria, L.
+ (2006). A new algorithm to calculate the nestedness temperature of
+ presence-absence matrices. \emph{J. Biogeogr.} 33, 924--935.
+
+ Stone, L. & Roberts, A. (1990). The checkerboard score and species
+ distributions. \emph{Oecologia} 85, 74--79.
+
+ Wright, D.H., Patterson, B.D., Mikkelson, G.M., Cutler, A. & Atmar,
+ W. (1998). A comparative analysis of nested subset patterns of species
+ composition. \emph{Oecologia} 113, 1--20.
+ }
+\author{ Jari Oksanen }
+
+\seealso{
+ In general, the functions should be used with \code{\link{oecosimu}}
+ which generates Null model communities to assess the nonrandomness of
+ nestedness patterns.
+ }
+\examples{
+data(sipoo)
+## Matrix temperature
+out <- nestedtemp(sipoo)
+out
+plot(out)
+plot(out, kind="incid")
+## Use oecosimu to assess the nonrandomness of checker board units
+nestedchecker(sipoo)
+oecosimu(sipoo, nestedchecker, "quasiswap")
+## Another Null model and standardized checkerboard score
+oecosimu(sipoo, nestedchecker, "r00", statistic = "C.score")
+}
+\keyword{ univar }
+
Modified: pkg/man/oecosimu.Rd
===================================================================
--- pkg/man/oecosimu.Rd 2008-08-27 09:31:33 UTC (rev 486)
+++ pkg/man/oecosimu.Rd 2008-08-27 12:49:07 UTC (rev 487)
@@ -1,43 +1,27 @@
\encoding{UTF-8}
\name{oecosimu}
\alias{oecosimu}
-\alias{nestedchecker}
-\alias{nestedn0}
-\alias{nesteddisc}
-\alias{nestedtemp}
\alias{commsimulator}
\alias{print.oecosimu}
-\alias{print.nestedchecker}
-\alias{print.nestedn0}
-\alias{print.nesteddisc}
-\alias{print.nestedtemp}
-\alias{plot.nestedtemp}
-\title{ Nestedness and Null Models for Islands or Patches }
+\title{ Null Models for Biological Communities }
\description{
- Patches or local communities are regarded as nested if they all could
- be subsets of the same community. In general, species poor communities
- should be subsets of species rich communities, and rare species should
- only occur in species rich communities. Null models generate random
- communities with different criteria to study the significance of
- nestedness.
+ Null models generate random communities with different criteria to
+ study the significance of nestedness or other community patterns. The
+ function only simulates binary (presence/absence) models with
+ constraint for total number of presences, and optionally for numbers
+ of species and/or species frequencies.
}
\usage{
oecosimu(comm, nestfun, method, nsimul = 99, burnin = 0, thin = 1,
statistic = "statistic", ...)
-nestedchecker(comm)
-nestedn0(comm)
-nesteddisc(comm)
-nestedtemp(comm, ...)
-\method{plot}{nestedtemp}(x, kind = c("temperature", "incidendce"),
- col=rev(heat.colors(100)), names = FALSE, ...)
commsimulator(x, method, thin=1)
}
\arguments{
- \item{comm}{Community data. }
+ \item{comm, x}{Community data. }
\item{nestfun}{Function to analyse nestedness. Some functions are
provided in \pkg{vegan}, but any function can be used if it accepts the
community as the first argument, and returns either a plain number or
@@ -52,61 +36,27 @@
\code{"swap"} and \code{"tswap"}.}
\item{statistic}{The name of the statistic returned by
\code{nestedfun}}
- \item{kind}{The kind of plot produced.}
- \item{x}{Matrix for \code{commsimulator} or a \code{plot} object.}
- \item{col}{Colour scheme for matrix temperatures.}
- \item{names}{Label columns and rows in the plot using names in \code{comm}.}
\item{\dots}{Other arguments to functions.}
}
\details{
+
Function \code{oecosimu} is a wrapper that evaluates a nestedness
statistic using function given by \code{nestfun}, and then simulates a
series of null models using \code{commsimulator}, and evaluates the
- nestedness statistic on these null models. The \pkg{vegan} packages
- contains some nestedness functions that are described below, and the
- generation of null models is described towards the end of this
- section.
+ statistic on these null models. The \pkg{vegan} packages contains some
+ nestedness functions that are described separately
+ (\code{\link{nestedchecker}}, \code{\link{nesteddisc}},
+ \code{\link{nestedn0}}, \code{\link{nestedtemp}}), but many other
+ functions can be used as long as they are meaningful with binary
+ community models. An applicable function must return either the
+ statistic as a plain number, or as a list element \code{"statistic"}
+ (like \code{\link{chisq.test}}), or in an item whose name is given in
+ the argument \code{statistic}. The statistic can be a single number
+ (like typical for a nestedness index), or it can be a vector. The
+ vector indices can be used to analyse site (row) or species (column)
+ properties, see \code{\link{treedive}} for an example.
- Function \code{netstedchecker} gives the number of checkerboard units,
- or 2x2 submatrices where both species occur once but on different
- sites (Stone & Roberts 1990). Function \code{nestedn0} implements
- nestedness measure N0 which is the number of absences from the sites
- which are richer than the most pauperate site species occurs
- (Patterson & Atmar 1986). Function \code{nesteddisc} implements
- discrepancy index which is the number of ones that should be shifted
- to fill a row with ones in a table arranged by species frequencies
- (Brualdi & Sanderson 1999). Function \code{nestedtemp} finds the
- matrix temperature which is defined as the sum of \dQuote{surprises}
- in arranged matrix. In arranged unsurprising matrix all species
- within proportion given by matrix fill are in the upper left corner of
- the matrix, and the surprise of the absence or presences is the
- diagonal distance from the fill line (Atmar & Patterson
- 1993). Function tries to pack species and sites to a low
- temperature (\enc{Rodríguez-Gironés}{Rodriguez-Girones} & Santamaria
- 2006), but this is an iterative procedure, and the temperatures
- usually vary among runs. Function \code{nestedtemp} also has a
- \code{plot} method which can display either incidences or temperatures
- of the surprises. Matrix temperature was rather vaguely described
- (Atmar & Patterson 1993), but
- \enc{Rodríguez-Gironés}{Rodriguez-Girones} & Santamaria (2006) are
- more explicit and their description is used here. However, the results
- probably differ from other implementations, and users should be
- cautious in interpreting the results. The details of calculations
- are explained in the \code{\link{vignette}} \emph{Design decisions
- and implementation} that you can read using functions
- \code{\link{vignette}} or \code{\link{vegandocs}}.
-
- In addition to these functions provided in \pkg{vegan}, any function
- can be used that takes \code{comm} as the first argument, and returns
- the nestedness index either as plain numeric value or in an item with
- name defined in \code{statistic} (which defaults to
- \code{"statistic"}). Function \code{\link{chisq.test}} is such a
- function, and examples show how to do this in general. If you write a
- function that may be useful to others, please consider submitting it
- to \pkg{vegan} for others to enjoy (you will be credited as an author
- of that function).
-
Function \code{commsimulator} implements null models for community
composition. The implemented models are \code{r00} which maintains the
number of presences but fills these anywhere so that neither species
@@ -131,7 +81,7 @@
marginal sums (Gotelli & Entsminger
2003). Method \code{swap} inspects submatrices so long that a swap
can be done. \enc{Miklós}{Miklos} & Podani (2004) suggest that this may lead into
- biased sequence, since some columns or rows may be more easily
+ biased sequences, since some columns or rows may be more easily
swapped, and they suggest trying a fixed number of times and
doing zero to many swaps at one step. This method is implemented by
method \code{tswap} or trial swap. Function \code{commsimulator} makes
@@ -144,7 +94,7 @@
account in estimating the \code{thin}. One swap still changes the
matrix only little, and it may be useful to
thin the results so that the statistic is only evaluated after
- \code{thin} steps.
+ \code{burnin} steps (and \code{thin}ned).
Methods \code{quasiswap} and \code{backtracking} are not sequential,
but each call produces a matrix that is independent of previous
@@ -177,20 +127,11 @@
with one added component called \code{oecosimu}. The \code{oecosimu}
component contains the simulated values of the statistic (item
\code{simulated}), the name of the \code{method}, two-sided \eqn{P}
- value and z-value of the statistic. The result returned by
- nestedness function must contain item called \code{statistic}, but
- the other components differ among functions. The
+ value and z-value of the statistic based on simulation. The
\code{commsimulator} returns a null model matrix or a swap of the
input matrix. }
\references{
- Atmar, W. & Patterson, B.D. (1993). The measurement of order and
- disorder in the distribution of species in fragmented
- habitat. \emph{Oecologia} 96, 373--382.
-
- Brualdi, R.A. & Sanderson, J.G. (1999). Nested species subsets, gaps,
- and discrepancy. \emph{Oecologia} 119, 256--264.
-
Gotelli, N.J. & Entsminger, N.J. (2001). Swap and fill algorithms in
null model analyis: rethinking the knight's tour. \emph{Oecologia}
129, 281--291.
@@ -203,18 +144,7 @@
\enc{Miklós}{Miklos}, I. & Podani, J. (2004). Randomization of presence-absence
matrices: comments and new algorithms. \emph{Ecology} 85, 86--92.
-
- Patterson, B.D. & Atmar, W. (1986). Nested subsets and the structure
- of insular mammalian faunas and archipelagos. \emph{Biol. J. Linnean
- Soc.} 28, 65--82.
- \enc{Rodríguez-Gironés}{Rodriguez-Girones}, M.A. & Santamaria, L.
- (2006). A new algorithm to calculate the nestedness temperature of
- presence-absence matrices. \emph{J. Biogeogr.} 33, 924--935.
-
- Stone, L. & Roberts, A. (1990). The checkerboard score and species
- distributions. \emph{Oecologia} 85, 74--79.
-
Wright, D.H., Patterson, B.D., Mikkelson, G.M., Cutler, A. & Atmar,
W. (1998). A comparative analysis of nested subset patterns of species
composition. \emph{Oecologia} 113, 1--20.
@@ -247,21 +177,19 @@
because it is slow, but it is still included for comparison.
If you wonder about the name of \code{oecosimu}, look at journal
- names in the References. }
+ names in the References (and more in \code{\link{nestedtemp}}). }
\seealso{ \code{\link{r2dtable}} generates table with given marginals but
- with entries above one. Function \code{\link[labdsv]{rndtaxa}}
- (\pkg{labdsv} package) randomizes a community table.}
+ with entries above one. Functions \code{\link{permatfull}} and
+ \code{\link{permatswap}} generate Null models for count data.
+ Function \code{\link[labdsv]{rndtaxa}}
+ (\pkg{labdsv} package) randomizes a community table. See also
+ \code{\link{nestedtemp}} (that also discusses other nestedness
+ functions) and \code{\link{treedive}} for another application. }
\examples{
-data(sipoo)
-## Matrix temperature
-out <- nestedtemp(sipoo)
-out
-plot(out)
-plot(out, kind="incid")
## Use the first eigenvalue of correspondence analysis as an index
## of structure: a model for making your own functions.
-## This is a minimal structure; fancier functions give fancier results
+data(sipoo)
caeval <- function(x) decorana(x, ira=1)$evals
out <- oecosimu(sipoo, caeval, "swap", burnin=100, thin=10)
out
More information about the Vegan-commits
mailing list