STRAPP: STructured Rate Permutations on Phylogenies
Description
Given a bammdata
object and a vector of (continuous)
trait data, assess whether the correlation between the trait and bamm
estimated speciation, extinction or net diversification rate is
significant using permutation. A set of posterior samples is randomly
drawn from the bammdata
object. If the trait is continuous,
this function calculates the correlation coefficients between the
trait and tip rates (observed correlation), as well as that with
permuted rates for each posterior sample. In a onetailed test for
positive correlations, the reported pvalue is the proportion of the
posterior samples in which the observed correlation is larger than the
correlations calculated with permuted rates. In a twotailed test, the
reported pvalue is the proportion of the posterior samples in which
the null correlation is as extreme as the correlation observed. If the
trait is binary, the U statistic of the MannWhitney test is
calculated instead of correlation coefficients to assess whether there
is a significant difference in rate between the two trait states. For
categorical traits with more than two states, the KruskalWallis rank
sum statistic is used.
Usage
1 2 3  traitDependentBAMM(ephy, traits, reps, rate = "speciation",
return.full = FALSE, method = "spearman", logrates = TRUE,
two.tailed = TRUE, traitorder = NA, nthreads = 1)

Arguments
ephy 
An object of class 
traits 
A vector of trait data, with names corresponding to tips in
the 
reps 
An integer specifying the number of permutations (i.e., the
number of posterior samples to randomly draw with replacement from the

rate 
A character string specifying which estimated rate from the

return.full 
A logical. If 
method 
A character string, must be one of 'spearman', 'pearson', 'mannwhitney', or 'kruskal'. Defaults to 'spearman'. You can specify just the initial letter. 
logrates 
A logical. If 
two.tailed 
A logical, used for continuous trait data. If

traitorder 
A character string specifying the direction of correlation for the alternative hypothesis. For continuous traits, it must be either "positive" or "negative"; only the initial letter is needed. For binary traits, it must be a string indicating states with increasing rate under the alternative hypothesis, separated by comma (e.g., 'A, B'). Onetailed test for categorical data with more than two states is not supported. 
nthreads 
Number of threads to use for parallelization of the
function. The R package 
Details
Tip rates –trait, speciation, extinction, or net diversification
rates– are permuted in a way such that pairwise covariances in rates
between species are maintained. That is, tips with the same
tipStates
still have the same rate after permutation. Posterior
samples are randomly selected with replacement from the
bammdata
object, so reps
could be smaller or larger than
the total number of samples in the object.
This function expects that the bammdata object and the trait data
have the same taxon set. It may be necessary to subset the trait data
and/or run subtreeBAMM
on the bammdata
object in
order to meet this requirement.
Value
A list with the following components:
estimate A numeric value for continous trait data: the average observed correlation between tip rates and the trait across the posterior samples. For categorical traits, it is a list showing the median speciesspecific rates for each trait state.
p.value A numeric value. The probability that the observed correlation is less than or equal to a sample from the null distribution.
method A character string, as input.
rate A character string, as input.
two.tailed A logical, as input.
gen An integer vector, recording which posterior samples were selected. Only present when
return.full
isTRUE
.obs.corr A numeric vector, the observed correlation coefficents for each posterior sample. Only present when
return.full
isTRUE
. For binary traits, centered U statistics (U  n1* n2/2; where n1 and n2 are the number of species in each state of the binary trait) is reported.null A numeric vector. The null distribution of correlation coefficients (or centered U statistics for binary traits) from permutation. Only present when
return.full
isTRUE
.
Author(s)
Dan Rabosky, Huateng Huang
References
Rabosky, D. L. and Huang, H., 2015. A Robust SemiParametric Test for Detecting TraitDependent Diversification. Systematic Biology 65: 181193.
Rabosky, D. L. 2014. Automatic detection of key innovations, rate shifts, and diversitydependence on phylogenetic trees. PLoS ONE 9:e89543.
Rabosky, D. L., F. Santini, J. T. Eastman, S. A. Smith, B. L. Sidlauskas, J. Chang, and M. E. Alfaro. 2013. Rates of speciation and morphological evolution are correlated across the largest vertebrate radiation. Nature Communications DOI: 10.1038/ncomms2958.
See Also
subtreeBAMM
Examples
1 2 3 4 5 6 7 8 9 10  # using a small subset of the fish data set (300 taxa) in Rabosky et al.
# 2013. Nat. Com. paper
data(fishes, events.fishes)
xx < getEventData(phy = fishes, eventdata = events.fishes,
nsamples = 500, type = "diversification")
# traits.fishes is the trait  body size
data(traits.fishes)
x < traitDependentBAMM(ephy = xx, traits = traits.fishes, reps = 1000,
return.full = TRUE, method = 's', logrates = TRUE,
two.tailed = TRUE)
