/packages/archive/2010/04.2010/04.29.2010/spacodi/man/spacodi.matrices.Rd

 1\name{spacodi.matrices}
 2
 3\alias{spacodi.matrices}
 4
 5\title{generating pairwise-distance matrices of phylogenetic diversity: Ist, Pst, Bst, and PIst}
 6
 7\description{
 8  This function automates the process of pairwise computation of measures of phylogenetic (or trait)
 9  diversity between all plots of a dataset. Average measures of diversity, from each plot to every other, 
10  are assembled into a distance matrix for use in downstream analyses (e.g., Mantel tests). 
11}
12
13\usage{spacodi.matrices(sp.plot, phy = NULL, sp.traits = NULL)}
14
15\arguments{
16  \item{sp.plot}{a community-phylogenetic dataset in \code{SPACoDi} format (see \code{\link{as.spacodi}})}
17  \item{phy}{a fully resolved phylogenetic tree, most sensibly ultrametric}
18  \item{sp.traits}{a species-by-trait(s) dataframe}
19}
20
21\details{
22  Either (but not both) a \code{phy} or \code{sp.traits} object is to be supplied along with the community dataset, \code{sp.plot}.
23  If a tree is given, pairwise values for \code{Ist}, \code{Pst}, \code{Bst}, \code{PIst} are estimated for every 
24  pair of unique plots using \code{\link{spacodi.calc}}. If fewer than two species are sampled for
25  particular plots, these plots are dynamically removed from the dataset (as phylogenetic diversities are 
26  incalculable in such cases). Analogously, matrices of pairwise \code{Ist}, \code{Tst}, \code{T*st}, \code{TAUst} are generated 
27  if a traits matrix is supplied. 
28}
29
30\value{A list of four distance matrices (the following measures are further explained in the \code{\link{spacodi.calc}} documentation):
31 \itemize{
32  \item{\code{Ist}}{: a distance matrix of average species turnover between plots}
33  \item{\code{Pst}}{: a distance matrix of average phylogenetic+species turnover between plots}
34  \item{\code{Bst}}{: a distance matrix of average phylogenetic turnover between plots}
35  \item{\code{PIst}}{: a distance matrix of \code{Pst}s, for presence | absence of species in plots}
36 }
37 See \code{\link{as.spacodi}} for the trait-based analogues of these measures. 
38}
39
40\references{
41  HARDY OJ and B SENTERRE. 2007. Characterizing the 
42  phylogenetic structure of communities by an additive partitioning of 
43  phylogenetic diversity. Journal of Ecology 95:493-506.
44}
45
46\author{Jonathan Eastman}
47
48\seealso{\code{\link{spacodi.calc}} for interpretation of results; see \code{\link[vegan]{mantel}} for 
49statistical comparison of dissimilarity matrices}
50
51\examples{
52# load a community data matrix, along with a tree
53data(sp.example)
54attributes(sp.example)
55attach(sp.example)
56sp.plot
57sp.tree
58sp.traits
59
60# randomly generate an 'environmental' variable
61env.fake <- data.frame(runif(ncol(sp.plot))) 
62names(env.fake) = "fake.env"
63row.names(env.fake)=names(sp.plot)
64e.f=dist(env.fake)
65
66# generate phylogenetic diversity matrices
67s.out=spacodi.matrices(sp.plot=sp.plot, phy=sp.tree)
68t.out=spacodi.matrices(sp.plot=sp.plot, sp.traits=sp.traits)
69
70# conduct Mantel tests, comparing pairwise distances between phylogenetic and environmental diversity
71for(ii in 1:length(s.out)) {
72	print(paste("### a test of environmental variation and ", names(s.out)[ii], sep=""))
73	print(mantel(e.f, s.out[[ii]]))
74	}
75	
76for(ii in 2:length(s.out)) {
77	print(paste("### testing trait variation and phylogenetic diversity: ", names(s.out)[ii], " and ", names(t.out)[ii], sep=""))
78	print(mantel(t.out[[ii]], s.out[[ii]]))
79	}
80	
81	
82}