/packages/archive/2010/04.2010/04.30.2010/spacodi/man/Bst.by.nodes.Rd
Unknown | 108 lines | 81 code | 27 blank | 0 comment | 0 complexity | 551b0bc549b77a96119b9b5719568bc8 MD5 | raw file
1\name{Bst.by.nodes} 2 3\alias{Bst.by.nodes} 4 5\title{conducting randomization tests of phylogenetic turnover through time} 6 7\usage{Bst.by.nodes(sp.plot, phy, obs.only = FALSE, return.all = TRUE, n.rep = 10, method = "1s", parm = NULL, dmat = NULL, rand.test = TRUE, r.rep = 10000)} 8 9\arguments{ 10 \item{sp.plot}{a community-phylogenetic dataset in \code{SPACoDi} format (see \code{\link{as.spacodi}})} 11 \item{phy}{a fully resolved phylogenetic tree, most sensibly ultrametric} 12 \item{obs.only}{a logical indicator determining whether only estimated \code{Bst}s for the empirical data are returned} 13 \item{return.all}{a logical indicator determing whether results for all nodes are returned for the empirical data (regardless of whether \code{Bst} is non-null)} 14 \item{n.rep}{number of permutations to perform on the dataset} 15 \item{method}{reshuffling or simulation procedure to perform (see details for optional methods)} 16 \item{parm}{additional parameters, required for methods \code{"1a", "2x", and "3x"} (see details)} 17 \item{dmat}{an optional matrix of spatial distances between plots, for use only with method \code{"3t"}} 18 \item{rand.test}{a logical indicator for whether a randomization test of observed and expected \code{Bst}s is performed} 19 \item{r.rep}{number of randomization iterations to perform} 20 21} 22 23\details{ 24 \code{Bst.by.nodes} is a function to conduct randomization tests on estimated and observed \code{Bst}s through time. 25 26 Bst is a measure of local phyletic proximity excess between individuals of distinct species, 27 thereby expressing phylogenetic turnover. This measure considers the balance between 28 phylogenetic diversity within and among plots. 29 30 \code{Bst.by.nodes} computes phylogenetic community diversity for nodes of 31 a phylogeny that subtend greater than two species and where nodes subtend species 32 that are sampled in multiple plots. 33 34 Note: whether for the empirical data or for permuted datasets, if fewer than two species are sampled in a given plot, the plot will be dynamically 35 removed from the dataset. This behavior can be controlled directly in \code{\link{spacodi.calc}} with teh \code{prune.plots} option. 36 37 For significance testing, permuted datasets may be generated by one of several \code{methods}: 38 \itemize{ 39 \item \code{method = "1a"} shuffling based on abundance classes of species (see \code{\link{resamp.1a}}); 40 requires specification of \code{abund.class.ratio} as a \code{parm} (see examples) 41 42 \item \code{method = "1s"} shuffling of abundances across entire dataset (see \code{\link{resamp.1s}}) 43 44 \item \code{method = "2s"} shuffling of abundances across species but within plots (see \code{\link{resamp.2s}}) 45 46 \item \code{method = "2x"} Gotelli swapping of abundances for pairs of species and within a pair of plots (see \code{\link{resamp.2x}}); 47 requires specification of \code{level} as a \code{parm} (see examples) 48 49 \item \code{method = "3i"} shuffling of abundances within species and among plots (see \code{\link{resamp.3i}}) 50 51 \item \code{method = "3t"} shuffling of abundances to adjacent plots but within species (see \code{\link{resamp.3t}}); if supplied, \code{dmat} 52 is used to condition abundance shuffling, where closer plots, on average, have higher likelihoods of abundances being swapped 53 54 \item \code{method = "3x"} Gotelli swapping of abundances for pairs of plots and within a pair of species (see \code{\link{resamp.3x}}); 55 requires specification of \code{level} as a \code{parm} (see examples) 56 57 \item \code{method = "r.sp.plot"} simulation of species-by-plots matrices, informed by empirical data (see \code{\link{r.sp.plot}}) 58 } 59} 60 61\value{ 62 \code{Bst.by.nodes} returns a list of three elements: 63 \itemize{ 64 \item \code{observed.Bst}{: estimated \code{Bst} for nodes of the tree (either all nodes, if \code{return.all=TRUE} or for only 65 those nodes for which \code{Bst} is non-null)} 66 \item \code{expected.Bst}{: expected \code{Bst} for all nodes of the emprical data for which \code{Bst} is calculable; nodes in 67 this element of the output array are row names} 68 \item \code{randomization.test}{: results from randomization tests of \code{Bst} for each node. Note: if randomization test is used, 69 some randomization iterations may return NA for particular nodes (see details above). The tally of valid expected 70 \code{Bst}s from permutation is recorded as a column in this element (i.e., \code{randomization.test$valid.comparisons}). 71 Be wary of significant results that are based off few valid comparisons.} 72 } 73} 74 75\references{ 76 HARDY OJ and B SENTERRE. 2007. Characterizing the 77 phylogenetic structure of communities by an additive partitioning of 78 phylogenetic diversity. Journal of Ecology 95:493-506. 79 80 HARDY OJ. 2008. Testing the spatial phylogenetic 81 structure of local communities: statistical performances of 82 different null models and test statistics on a locally neutral 83 community. Journal of Ecology 96:914-926. 84} 85 86\author{Jonathan Eastman and Timothy Paine} 87 88\seealso{\code{\link{spacodi.calc}} for interpretation of results; \code{\link{randomization.test.sp}}} 89 90\examples{ 91# load a species-by-plots matrix, along with a tree 92data(sp.example) 93attributes(sp.example) 94attach(sp.example) 95sp.plot 96sp.tree 97 98# generate a plot of observed and expected Bst 99sp.permut<-Bst.by.nodes(sp.plot=sp.plot, phy=sp.tree, n.rep=35) 100sp.permut$randomization.test 101plot(sp.tree) 102nodelabels() 103 104# plot observed and expected Bst 105Bst.permutation.plot(Bst.permutations=sp.permut, envelope=FALSE) 106 107} 108