\name{Bst.by.nodes}

\alias{Bst.by.nodes}

\title{conducting randomization tests of phylogenetic turnover through time}

\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)}

\arguments{
  \item{sp.plot}{a community-phylogenetic dataset in \code{SPACoDi} format (see \code{\link{as.spacodi}})}
  \item{phy}{a fully resolved phylogenetic tree, most sensibly ultrametric}
  \item{obs.only}{a logical indicator determining whether only estimated \code{Bst}s for the empirical data are returned}
  \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)}
  \item{n.rep}{number of permutations to perform on the dataset}
  \item{method}{reshuffling or simulation procedure to perform (see details for optional methods)}
  \item{parm}{additional parameters, required for methods \code{"1a", "2x", and "3x"} (see details)}
  \item{dmat}{an optional matrix of spatial distances between plots, for use only with method \code{"3t"}}
  \item{rand.test}{a logical indicator for whether a randomization test of observed and expected \code{Bst}s is performed}
  \item{r.rep}{number of randomization iterations to perform}

}

\details{
  \code{Bst.by.nodes} is a function to conduct randomization tests on estimated and observed \code{Bst}s through time.   

  Bst is a measure of local phyletic proximity excess between individuals of distinct species, 
  thereby expressing phylogenetic turnover.  This measure considers the balance between 
  phylogenetic diversity within and among plots. 
    
  \code{Bst.by.nodes} computes phylogenetic community diversity for nodes of 
  a phylogeny that subtend greater than two species and where nodes subtend species 
  that are sampled in multiple plots. 
  
  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 
  removed from the dataset. This behavior can be controlled directly in \code{\link{spacodi.calc}} with teh \code{prune.plots} option.
    
  For significance testing, permuted datasets may be generated by one of several \code{methods}:
    \itemize{
	\item \code{method = "1a"} shuffling based on abundance classes of species (see \code{\link{resamp.1a}}); 
	requires specification of \code{abund.class.ratio} as a \code{parm} (see examples)
	
	\item \code{method = "1s"} shuffling of abundances across entire dataset (see \code{\link{resamp.1s}})

	\item \code{method = "2s"} shuffling of abundances across species but within plots (see \code{\link{resamp.2s}})
	
	\item \code{method = "2x"} Gotelli swapping of abundances for pairs of species and within a pair of plots (see \code{\link{resamp.2x}}); 
	requires specification of \code{level} as a \code{parm} (see examples)
	
	\item \code{method = "3i"} shuffling of abundances within species and among plots (see \code{\link{resamp.3i}})
	
	\item \code{method = "3t"} shuffling of abundances to adjacent plots but within species (see \code{\link{resamp.3t}}); if supplied, \code{dmat} 
	is used to condition abundance shuffling, where closer plots, on average, have higher likelihoods of abundances being swapped

	\item \code{method = "3x"} Gotelli swapping of abundances for pairs of plots and within a pair of species (see \code{\link{resamp.3x}}); 
	requires specification of \code{level} as a \code{parm} (see examples)
	
	\item \code{method = "r.sp.plot"} simulation of species-by-plots matrices, informed by empirical data (see \code{\link{r.sp.plot}})
  }
}

\value{  
  \code{Bst.by.nodes} returns a list of three elements:
  \itemize{
    \item \code{observed.Bst}{: estimated \code{Bst} for nodes of the tree (either all nodes, if \code{return.all=TRUE} or for only 
	those nodes for which \code{Bst} is non-null)}
	\item \code{expected.Bst}{: expected \code{Bst} for all nodes of the emprical data for which \code{Bst} is calculable; nodes in 
	this element of the output array are row names}
	\item \code{randomization.test}{: results from randomization tests of \code{Bst} for each node. Note: if randomization test is used, 
	some randomization iterations may return NA for particular nodes (see details above). The tally of valid expected 
	\code{Bst}s from permutation is recorded as a column in this element (i.e., \code{randomization.test$valid.comparisons}).  
	Be wary of significant results that are based off few valid comparisons.}
  }
}

\references{
  HARDY OJ and B SENTERRE. 2007. Characterizing the 
  phylogenetic structure of communities by an additive partitioning of 
  phylogenetic diversity. Journal of Ecology 95:493-506.
  
  HARDY OJ. 2008. Testing the spatial phylogenetic 
  structure of local communities: statistical performances of 
  different null models and test statistics on a locally neutral 
  community. Journal of Ecology 96:914-926.
}

\author{Jonathan Eastman and Timothy Paine}

\seealso{\code{\link{spacodi.calc}} for interpretation of results; \code{\link{randomization.test.sp}}}

\examples{
# load a species-by-plots matrix, along with a tree
data(sp.example)
attributes(sp.example)
attach(sp.example)
sp.plot
sp.tree

# generate a plot of observed and expected Bst
sp.permut<-Bst.by.nodes(sp.plot=sp.plot, phy=sp.tree, n.rep=35)
sp.permut$randomization.test
plot(sp.tree)
nodelabels()

# plot observed and expected Bst
Bst.permutation.plot(Bst.permutations=sp.permut, envelope=FALSE)

}