search.shift: Locating shifts in phenotypic evolutionary rates

Description

The function search.shift (Castiglione et al. 2018) tests whether individual clades or group of tips dispersed through the phylogeny evolve at different RRphylo rates as compared to the rest of the tree.

Usage

search.shift(RR, status.type = c("clade", "sparse"),node = NULL, state
  = NULL, cov = NULL, nrep = 1000, f = NULL)

Value

Under "clade" case without specifying nodes (i.e. 'auto-recognize') a list including:

$all.clades for each detected node, the data-frame includes the average rate difference (computed as the mean rate over all branches subtended by the node minus the average rate for the rest of the tree) and the probability that it do represent a real shift. Probabilities are contrasted to simulations shuffling the rates across the tree branches for a number of replicates specified by the argument nrep. Note that the p-values refer to the number of times the real average rates are larger (or smaller) than the rates averaged over the rest of the tree, divided by the number of simulations. Hence, large rates are significantly larger than the rest of the tree (at alpha = 0.05), when the probability is > 0.975; and small rates are significantly small for p < 0.025.

$single.clades the same as with 'all.clades' but restricted to the largest/smallest rate values along a single lineage (i.e. nested clades with smaller rate shifts are excluded).

Under "clade" condition by specifying the node

argument:

$all.clades.together if more than one node is tested, this specifies the average rate difference and the significance of the rate shift, by considering all the specified nodes as evolving under a single rate. As with the 'auto-recognize' feature, large rates are significantly larger than the rest of the tree (at alpha = 0.05), when the probability is > 0.975; and small rates are significantly small for p < 0.025.

$single.clades gives the significance for individual clades tested individually against the rest of the tree ($singles) and by excluding the rate values of other shifting clades from the rate vector of the rest of the tree ($no.others)

Under the "sparse" condition:

$state.results for each state, the data-frame includes the average rate difference (computed as the mean rate over all leaves evolving under a given state, minus the average rate for each other state or the rest of the tree) and the probability that the shift is real. Large rates are significantly larger (at alpha = 0.05), when the probability is > 0.975; and small rates are significantly small for p < 0.025. States are compared pairwise.

Under all circumstances, if 'cov' values are provided to the function, search.shift returns as $rates object the vector of residuals of RRphylo rates versus cov regression.

The output always has an attribute "Call" which returns an unevaluated call to the function.

Arguments

RR: an object fitted by the function RRphylo.
status.type: whether the "clade" or "sparse" condition must be tested.
node: under the "clade" condition, the node/s (clades) to be tested for the rate shift. If node is left unspecified, the function performs under the 'auto-recognize' feature, meaning it will automatically test individual clades for deviation of their rates from the background rate of the rest of the tree (see details).
state: the named vector of states for each tip, to be provided under the "sparse" condition.
cov: the covariate vector to be indicated if its effect on rate values must be accounted for. Contrary to RRphylo, cov needs to be as long as the number of tips of the tree.
nrep: the number of simulations to be performed for the rate shift test, by default nrep is set at 1000.
f: the size of the smallest clade to be tested. By default, nodes subtending to one tenth of the tree tips are tested.

Author

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

Details

Under the 'auto-recognize' mode, search.shift automatically tests individual clades (ranging in size from one half of the tree down to f tips) for deviation of their rates from the background rate of the rest of the tree. An inclusive clade with significantly high rates is likely to include descending clades with similarly significantly high rates. Hence, under 'auto-recognize' search.shift scans clades individually and selects only the node subtending to the highest difference in mean absolute rates as compared to the rest of the tree. If the argument node ("clade" condition) is provided, the function computes the difference between mean rate values of each clade and the rest of the tree, and compares it to a random distribution of differences generated by shuffling rates across tree branches. Additionally, if more than one node is indicated, the rate difference for one clade is additionally computed by excluding the rate values of the others from the rate vector of the rest of the tree. Also, all the clades are considered as to be under a common rate regime and compared as a single group to the rest of the tree.

References

Castiglione, S., Tesone, G., Piccolo, M., Melchionna, M., Mondanaro, A., Serio, C., Di Febbraro, M., & Raia, P.(2018). A new method for testing evolutionary rate variation and shifts in phenotypic evolution. Methods in Ecology and Evolution, 9: 974-983.doi:10.1111/2041-210X.12954

Examples

Run this code

if (FALSE) {
data("DataOrnithodirans")
DataOrnithodirans$treedino->treedino
DataOrnithodirans$massdino->massdino
DataOrnithodirans$statedino->statedino
cc<- 2/parallel::detectCores()

RRphylo(tree=treedino,y=massdino,clus=cc)->dinoRates

# Case 1. Without accounting for the effect of a covariate

# Case 1.1 "clade" condition
# with auto-recognize
search.shift(RR=dinoRates,status.type="clade")->SSauto
# testing two hypothetical clades
search.shift(RR=dinoRates,status.type="clade",node=c(696,746))->SSnode

# Case 1.2 "sparse" condition
# testing the sparse condition.
search.shift(RR=dinoRates,status.type= "sparse",state=statedino)->SSstate


# Case 2. Accounting for the effect of a covariate

# Case 2.1 "clade" condition
search.shift(RR=dinoRates,status.type= "clade",cov=massdino)->SSauto.cov

# Case 2.2 "sparse" condition
search.shift(RR=dinoRates,status.type="sparse",state=statedino,cov=massdino)->SSstate.cov
    }

Run the code above in your browser using DataLab