/packages/archive/2010/04.2010/04.29.2010/spacodi/man/randomization.test.sp.Rd

 1\name{randomization.test.sp}
 2\alias{randomization.test.sp}
 3\title{testing significant by randomization}
 4\description{\code{randomization.test.sp} is a function for conducting significance-testing by randomization.}
 5\usage{randomization.test.sp(obs = obs, exp = exp, iter = 10000, return.all = FALSE, two.tailed = TRUE)}
 6
 7\arguments{
 8  \item{obs}{an vector of observed data}
 9  \item{exp}{an vector of expected values}
10  \item{iter}{number of randomization iterations to perform}
11  \item{return.all}{a logical identifier controlling whether all randomization comparisons are output into a vector}
12  \item{two.tailed}{a logical identifier indicating whether randomization test should be two-tailed}
13}
14
15\details{Given a set of observed and expected values, \code{iter} comparisons between the vectors are performed.  
16Expecting the sign of these comparisons to be random, if a large proportion of comparisons are in a particular 
17direction, support is lent for a true difference in means.  For instance, if 90 percent of comparisons suggest 
18that observed data are larger than expected, an approximate randomization \code{p}-value is interpreted to be 0.20. If 
19a single value is supplied for the observed data, this method will be akin to finding the quantile (\code{q})in the expected values
20where the observed datum appears. Under \code{two.tailed=TRUE}, the resulting \code{p.value} from this function will be twice (\code{q}), 
21for an observed datum in the left tail of the expected distribution, or twice (\code{1-q}) for the opposite tail. }
22
23\value{ A list of at most two primary elements:
24    \itemize{
25    \item \code{differences}{: the vector of all comparisons between \code{obs} and \code{exp} if \code{return.all=TRUE}}
26	\item \code{p.value}{: result(s) from the randomization test; if \code{two.tailed=FALSE}, \code{p}-values from both tails are returned}
27	}
28	Note: be wary of significant results that are based off few comparisons. If the number of iterations exceeds the length of the
29	empirical data, a warning will be issued.
30}
31
32\author{Jonathan Eastman}
33
34\examples{
35
36# generate a random tree
37foo=bd.tree(b=0.02, d=0, taxa.stop=25)
38
39# get nodes and times
40node.time.extractor(foo, start.time=0.35, stop.time=0.80, return.times=TRUE, proportion=TRUE)
41
42# visualize the correspondence
43plot(foo)
44nodelabels()
45
46## an example of comparing observed and expected Bst at nodes ##
47sim=sim.spacodi(missing=0.01,sim.tree=TRUE)
48s=sim$sp.plot
49p=sim$sp.tree
50
51# get nodes for a time-slice
52n.t=node.time.extractor(phy=p,start.time=0.25,stop.time=0.75)
53
54# get Bsts for nodes
55o=Bst.by.nodes(sp.plot=s, phy=p, obs.only=TRUE)[[1]]
56obs=o[!is.na(match(o[,"node.ID"], n.t$nodes)),1]
57
58# compile expected Bst-values from data reshuffling
59Bst.by.nodes(sp.plot=s, phy=p, n.rep=5, method="1s")[[2]]->exps
60e=exps[!is.na(match(row.names(exps), n.t$nodes)),]
61exp=unname(unlist(e))
62
63# randomization test of observed and expected Bst
64randomization.test.sp(obs=obs, exp=exp, iter=100, two.tailed=TRUE)
65}