/packages/archive/2010/04.2010/04.30.2010/spacodi/man/Bst.by.nodes.Rd

  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