traitDependentBAMM {BAMMtools}

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 one-tailed test for positive correlations, the reported p-value is the proportion of the posterior samples in which the observed correlation is larger than the correlations calculated with permuted rates. In a two-tailed test, the reported p-value 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 Mann-Whitney 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 Kruskal-Wallis rank sum statistic is used.

Usage

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 bammdata.

traits

A vector of trait data, with names corresponding to tips in the bammdata object. It can be numeric or categorical.

reps

An integer specifying the number of permutations (i.e., the number of posterior samples to randomly draw with replacement from the bammdata object).

rate

A character string specifying which estimated rate from the bammdata object to use for testing correlation, must be one of 'speciation', 'extinction', 'net diversification' or 'trait'. Defaults to 'speciation'. You can specify just the initial letter. Ignored for trait event data.

return.full

A logical. If TRUE, the list of posterior samples, the observed correlation for each posterior sample, and the null distribution will be included in the returned object. Defaults to FALSE.

method

A character string, must be one of 'spearman', 'pearson', 'mann-whitney', or 'kruskal'. Defaults to 'spearman'. You can specify just the initial letter.

logrates

A logical. If TRUE log-transform the rates before analysis. Defaults to TRUE. This can only matter for the pearson correlation.

two.tailed

A logical, used for continuous trait data. If TRUE, perform a two-tailed statistical test (i.e., if the null distribution is symmetric, it is equivalent to doubling the p-value). Defaults to TRUE.

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'). One-tailed 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 parallel must be loaded for nthreads > 1.

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 bamm-data 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 bamm-data 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 species-specific 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 is TRUE.

• obs.corr: A numeric vector, the observed correlation coefficents for each posterior sample. Only present when return.full is TRUE. 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 is TRUE.

Author(s)

Dan Rabosky, Huateng Huang

References

http://bamm-project.org/

Rabosky, D. L. and Huang, H., 2015. A Robust Semi-Parametric Test for Detecting Trait-Dependent Diversification. Systematic Biology 65: 181-193.

Rabosky, D. L. 2014. Automatic detection of key innovations, rate shifts, and diversity-dependence 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

# 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)