[Vegan-commits] r476 - pkg/man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Fri Aug 15 02:03:18 CEST 2008
Author: psolymos
Date: 2008-08-15 02:03:18 +0200 (Fri, 15 Aug 2008)
New Revision: 476
Modified:
pkg/man/adipart.Rd
pkg/man/permatfull.Rd
pkg/man/tsallis.Rd
Log:
documentation update and corrections
Modified: pkg/man/adipart.Rd
===================================================================
--- pkg/man/adipart.Rd 2008-08-14 15:28:07 UTC (rev 475)
+++ pkg/man/adipart.Rd 2008-08-15 00:03:18 UTC (rev 476)
@@ -9,8 +9,10 @@
In additive diversity partitioning, mean values of alpha diversity at lower levels of a sampling hierarchy are compared to the total number of species in the entire data set (gamma diversity) in the form: gamma = mean(alpha) + beta. Thus beta = gamma - mean(alpha).
}
\usage{
-adipart(matr, strata, hclass = NULL, method="trad", index=c("richness", "shannon", "simpson"),
-scales=seq(0, 2, 0.2), weights = "unif", test = TRUE, permtype = "full", times = 100, crit = 0.05,
+adipart(matr, strata, hclass = NULL, method="trad",
+index=c("richness", "shannon", "simpson"),
+scales=seq(0, 2, 0.2), weights = "unif", test = TRUE,
+permtype = "full", times = 100, crit = 0.05,
burnin = 10000, results = FALSE, ...)
\method{print}{adipart}(x, ...)
\method{summary}{adipart}(object, digits = 3, ...)
@@ -24,49 +26,72 @@
\item{method}{character, either \code{"trad"} for traditional diversity indices (see \code{index} argument for specifications), or \code{"tsallis"} for Tsallis diversity (see \code{scales} argument for specifications).}
\item{index}{character, one of (if \code{habitat} is not \code{NULL}) or combination of (if \code{habitat = NULL}) \code{c("richness", "shannon", "simpson")}.}
\item{scales}{vector for scales of the Tsallis diversity (see \code{\link{tsallis}} for details).}
- \item{weights}{character, \code{"unif"} for uniform weights, \code{"prop"} for weighting proportional to sample abundances.}
- \item{test}{logical, whether a permutation test should be applied.}
+ \item{weights}{character, \code{"unif"} for uniform weights, \code{"prop"} for weighting proportional to sample abundances to use in weighted averaging of individual alpha values within strata of a given level of the sampling hierarchy.}
+ \item{test}{logical, whether a permutation test should be applied. If \ code{FALSE}, only observed values are returned.}
\item{permtype}{character, \code{"full"} for permutation of community matrix via \code{\link{permatfull}}, \code{"swap"} for permutation via \code{\link{permatswap}}. Only used if \code{test = TRUE} and \code{matr} is not of class 'permat'.}
\item{times}{number of permutation to use if \code{matr} is not of class 'permat'.}
\item{crit}{two sided critical level for calculating confidence limits of the expected values. Only used if \code{test = TRUE}.}
\item{burnin}{number of burnin steps when \code{permtype = "swap"} (see \code{\link{permatswap}}).}
\item{results}{logical, whether null model results (individual alpha and beta diversity values) should be returned, only available for "oneway" design (\code{habitat = NULL}) if \code{test = TRUE}.}
- \item{x, object}{an object of class 'adp'.}
+ \item{x, object}{an object of class 'adipart'.}
\item{digits}{number of significant digits to use in the output.}
\item{rel.yax}{logical or \code{NULL}, \code{TRUE} for relative scaling of the y axis. The default (\code{NULL}) sets the scaling according to specific design ("oneway" or "twoway") criteria.}
\item{ymax}{maximum of the vertical axis of the plot. Useful when \code{rel.yax = FALSE} and more than one plot should have same scales. \code{ymax} is ignored if it is lower than highest value to be plotted.}
- \item{p.legend}{position of the legend box for P values, can be character of two coordinates, see \code{\link{legend}} for details. Use extreme large values to move the box out of the plotting region.}
+ \item{p.legend}{position of the legend box for p-values, can be character of two coordinates, see \code{\link{legend}} for details. Use extreme large values to move the box out of the plotting region.}
\item{\dots}{other arguments, e.g. arguments for \code{\link{permatfull}}, \code{\link{permatswap}}, \code{\link{par}} or \code{\link{print}}.}
}
\details{
-Soon to be updated.
+Additive diversity partitioning means that mean alpha and beta diversity adds up to gamma diversity, thus beta diversity is measured in the same dimensions as alpha and gamma (Lande 1996). This additive procedure is than extended across multiple scales in a hierarchical sampling design with \eqn{i = 1, 2, 3, \ldots, m} levels of sampling (Crist et al. 2003). Samples in lower hierarchical levels are nested within higher level units, thus from \eqn{i=1} to \eqn{i=m} grain size is increasing under constant survey extent. At each level \eqn{i}, \eqn{\alpha_i} denotes average diversity found within samples.
-Details here on one- and twoway designs, indices & Tsallis.
+At the highest sampling level, the diversity components are calculated as
-Also randomisation (permat object, or for large problems, better to do it within adipart function call).
+\deqn{\beta_m = \gamma - \alpha_m}{beta_m = gamma - alpha_m}
+
+For each lower sampling level as
+\deqn{\beta_i = \alpha_{i+1} - \alpha_i}{beta_i = alpha_i+1 - alpha_i}
+
+Then, the additive partition of diversity is
+
+\deqn{\gamma = \alpha_1 + \sum_{i=1}^m \beta_i}{gamma = alpha_1 + sum(beta_i)}
+
+Average alpha components can be weighted uniformly (\code{weight="unif"}) to calculate it as simple average, or proportionally to sample abundances (\code{weight="prop"}) to calculate it as weighted average as follows
+
+\deqn{\alpha_i = \sum_{j=1}^{n_i} D_{ij} w_{ij}}{alpha_i = sum(D_ij*w_ij)}
+
+where \eqn{D_{ij}} is the diversity index and \eqn{w_{ij}} is the weight calculated for the \eqn{j}th sample at the \eqn{i}th sampling level.
+
+The implementation of 'traditional' (\code{method="trad"}) 'oneway' (\code{hclass=NULL}) additive diversity partitioning follows Crist et al. 2003. This is 'traditional' in the sense, that it it is based on species richness (\eqn{S}, not \eqn{S-1}), Shannon's and Simpson's diversity indices. This is 'oneway' in the sense that habitat differences are assumed negligible (or, at least, well balanced or randomly sampled within strata), thus diversity partitioning is made according to successively larger grain sizes in the hierarchically nested sampling design.
+
+The expected diversity components are calculated \code{times} times by individual based randomisation of the community data matrix. This is done by the \code{\link{permatfull}} (\code{permtype="full"}) or the \code{\link{permatswap}} (\code{permtype="swap"}) functions. Row and column sums are fixed by default, to change this behaviour, use the \code{fixedmar} argument. Restricted permutations can be set via the \code{reg} and \code{hab} arguments of these functions. Input objects can be either matrices, or objects of class 'permat'. For large community data sets and several thousands of permutations, it is advisable to use a matrix as input object to overcome memory usage problems (randomisation is made internally). If identical random matrices are needed for different computations, than it can be useful to make an object of 'permat' prior these analyses and use the 'permat' object as input.
+
+The 'twoway' design (\code{hclass!=NULL}) can be used to compare diversity partitions among discrete habitat classes, and to calculate differentiation (beta diversity) among these habitat classes (Wagner et al. 2000). Within each habitat classes, the same sampling hierarchy is used, and among haitat diverity is calculated as the highest level beta component (\eqn{\beta_m}). The current implementation of null model testing for this 'twoway' design is based on the comparison of observed diversity components in a given habitat class with the expected components for all habitat classes.
+
+The 'non-traditional' way of additive diversity partitioning is made via the Tsallis generalised entropy function (\code{method="tsallis"}) Scales of the scale parameter \eqn{q} can be set by the \code{scales} argument.
}
\note{
-Please ensure thet \code{strata} and \code{habitat} are meaningfully compiled (i.e. there are no missing states of the combinations), because at the moment there are no checks for that in the code.
+Please ensure that \code{strata} and \code{hclass} are meaningfully compiled (i.e. there are no missing states of the combinations), because at the moment there are no checks for that in the code. If number of observations within strata are very few, or not well balanced, than the permutation algorithm may fail to do acceptable randomisation.
}
\value{
-An object of class 'adipart':
+An object of class 'adipart' with components:
\item{input}{input objects (\code{m = matr}, \code{f = strata}, \code{h = habitat}) and the function call (\code{call}).}
- \item{obs}{observed diversity components (alpha, beta, and SE for alpha).}
+ \item{obs}{observed diversity components (mean alpha, beta, and standard error for alpha).}
\item{exp}{expected diversity components, both elements with items \code{p.value}, \code{mean}, lower and upper confidence limits (\code{cl1}, \code{cl2}) and starndardized effect size (\code{ses}, (observed - mean(expected)) / sd(expexted)):
- \item{alpha}{expected alpha components,}
- \item{beta}{expected beta components.}
- }
+
+ \code{alpha} expected alpha components,
+
+ \code{beta} expected beta components.}
\item{res}{null model distribution for the tested alpha and beta diversity values (\code{NULL} if \code{results = FALSE}):
- \item{alpha}{null model distribution for alpha diversity, rows are permutations, columns are elements according to the \code{obs$alpha} matrix without the last row for gamma diversity,}
- \item{beta}{null model distribution for beta diversity, rows are permutations, columns are elements according to the \code{obs$beta} matrix.}
- }
+
+ \code{alpha} null model distribution for alpha diversity, rows are permutations, columns are elements according to the \code{obs$alpha} matrix without the last row for gamma diversity,
+
+ \code{beta} null model distribution for beta diversity, rows are permutations, columns are elements according to the \code{obs$beta} matrix.}
}
\references{
-Lande, R. 1996. Statistics and partitioning of species diversity, and similarity among multiple communities. Oikos, 76, 5-13.
+Lande, R. 1996. Statistics and partitioning of species diversity, and similarity among multiple communities. \emph{Oikos}, 76, 5-13.
-Crist, T.O., Veech, J.A., Gering, J.C. and Summerville, K.S. 2003. Partitioning species diversity across landscapes and regions: a hierarchical analysis of $\alpha$, $\beta$, and $\gamma$-diversity. Am. Nat., 162, 734-743.
+Crist, T.O., Veech, J.A., Gering, J.C. and Summerville, K.S. 2003. Partitioning species diversity across landscapes and regions: a hierarchical analysis of $\alpha$, $\beta$, and $\gamma$-diversity. \emph{Am. Nat.}, 162, 734-743.
-Wagner, H. H., Wildi, O. and Ewald, K.C. 2000. Additive partitioning of plant species diversity in an agricultural mosaic landscape. Landscape Ecology, 15, 219-227.
+Wagner, H. H., Wildi, O. and Ewald, K.C. 2000. Additive partitioning of plant species diversity in an agricultural mosaic landscape. \emph{Landscape Ecology}, 15, 219-227.
}
\author{Peter Solymos, \email{Solymos.Peter at aotk.szie.hu}}
\seealso{See \code{\link{permatfull}} and \code{\link{permatswap}} for permutation settings, and \code{\link{tsallis}} for Tsallis entropy.}
Modified: pkg/man/permatfull.Rd
===================================================================
--- pkg/man/permatfull.Rd 2008-08-14 15:28:07 UTC (rev 475)
+++ pkg/man/permatfull.Rd 2008-08-15 00:03:18 UTC (rev 476)
@@ -18,8 +18,10 @@
several tests might be applied on the same set of random matrices. }
\usage{
-permatfull(m, fixedmar = "both", reg = NULL, hab = NULL, mtype = "count", times = 100)
-permatswap(m, reg = NULL, hab = NULL, mtype = "count", method = "swap", times = 100, burnin = 10000, thin = 1000)
+permatfull(m, fixedmar = "both", reg = NULL,
+hab = NULL, mtype = "count", times = 100)
+permatswap(m, reg = NULL, hab = NULL, mtype = "count",
+method = "swap", times = 100, burnin = 10000, thin = 1000)
\method{plot}{permat}(x, ...)
\method{summary}{permat}(object, ...)
\method{print}{summary.permat}(x, digits = 2, ...)
@@ -57,8 +59,8 @@
fixed marginals and matrix fill at the same time.
The 'swapcount' algorithm tries to find 2x2 submatrices (identified by 2 random row and 2 random column indices), that
-can be swapped in order to leave column and row totals and fill unchanged. First, the algorithm finds the largest value ($LVS$)
-in the submatrix that can be swapped and whether in diagonal or antidiagonal way. Submatrices that contain values larger than zero in either diagonal or antidiagonal position can be swapped. Swap means that the values in diagonal or antidiagonal positions are decreased by $LVS$, while remaining cells are increased by $LVS$. A swap is made only if fill doesn't change.
+can be swapped in order to leave column and row totals and fill unchanged. First, the algorithm finds the largest value
+in the submatrix that can be swapped ($d$) and whether in diagonal or antidiagonal way. Submatrices that contain values larger than zero in either diagonal or antidiagonal position can be swapped. Swap means that the values in diagonal or antidiagonal positions are decreased by $d$, while remaining cells are increased by $d$. A swap is made only if fill doesn't change.
Constraints on row/colum sums, matrix fill, total sum and sums within
strata can be checked by the \code{summary} method. \code{plot} method is for
Modified: pkg/man/tsallis.Rd
===================================================================
--- pkg/man/tsallis.Rd 2008-08-14 15:28:07 UTC (rev 475)
+++ pkg/man/tsallis.Rd 2008-08-15 00:03:18 UTC (rev 476)
@@ -27,13 +27,13 @@
\details{
The Tsallis diversity (also equivalent to Patil and Taillie diversity) is a one-parametric generalised entropy function, defined as:
-\deqn{H_q = \frac{1}{q-1} (1-\sum p_i^q)}{H.q = 1/(q-1)(1-sum(p^q))}
+\deqn{H_q = \frac{1}{q-1} (1-\sum_{i=1}^S p_i^q)}{H.q = 1/(q-1)(1-sum(p^q))}
-where \eqn{q} is a scale parameter (Tsallis 1988, Tothmeresz 1995). This diversity is concave for all \eqn{q>0}, but non-additive (Keylock 2005). For \eqn{q=0} it gives the number of species minus one, as \eqn{q} tends to 1 this gives Shannon diversity, for \eqn{q=2} this gives the Simpson index (see function \code{\link{diversity}}.
+where \eqn{q} is a scale parameter, \eqn{S} the number of species in the sample (Tsallis 1988, Tothmeresz 1995). This diversity is concave for all \eqn{q>0}, but non-additive (Keylock 2005). For \eqn{q=0} it gives the number of species minus one, as \eqn{q} tends to 1 this gives Shannon diversity, for \eqn{q=2} this gives the Simpson index (see function \code{\link{diversity}}).
When \code{norm = TRUE}, \code{tsallis} gives values normalized by the maximum:
-\deqn{H_q(max) = \frac{S^(1-q)-1}{1-q}}{H.q(max) = (S^(1-q)-1)/(1-q)}
+\deqn{H_q(max) = \frac{S^{1-q}-1}{1-q}}{H.q(max) = (S^(1-q)-1)/(1-q)}
where \eqn{S} is the number of species. As \eqn{q} tends to 1, maximum is defined as \eqn{ln(S)}.
@@ -52,7 +52,7 @@
Patil, GP and Taillie, C. (1982). Diversity as a concep and its measurement.
\emph{J. Am. Stat. Ass.} 77, 548--567.
-Keylock, CJ (2005).Simpson diversity and the Shannon-Wiener index as special cases of a generalized entropy.
+Keylock, CJ (2005). Simpson diversity and the Shannon-Wiener index as special cases of a generalized entropy.
\emph{Oikos} 109, 203--207.
}
\author{Peter Solymos, based on the code of Roeland Kindt and Jari Oksanen written for \code{renyi}}
More information about the Vegan-commits
mailing list