R: Detections of shifts in the OU process along a phylogeny.

OUshifts {phylolm} | R Documentation

## Detections of shifts in the OU process along a phylogeny.

### Description

Trait data is fitted to a phylogeny using an Ornstein-Uhlenbeck (OU) process, such that the mean (or selection optimum) of the process may change in one or more edges in the tree. The number and location of changes, or shifts, is estimated using an information criterion.

### Usage

    OUshifts(y, phy, method = c("mbic", "aic", "bic", "saic", "sbic"),
             nmax, check.pruningwise = TRUE)

### Arguments

`y` | values for the trait data.
`phy` | a phylogenetic tree of type phylo with branch lengths.
`method` | a method for model selection (see details below).
`nmax` | maximum allowed number of shifts.
`check.pruningwise` | if TRUE, the algorithm checks if the ordering of the edges in phy are in pruningwise order.

### Details

This function does not accept multivariate data (yet): `y` should be a vector named with species labels. The data `y` and the tree `phy` need to contain the same species. The user can choose among various information criteria. Each criterion seeks to minimize the value of -2 \log[likelihood(y, M)] + penalty(M), where M is an OU model with m shifts, placed on various edges along the phylogeny. All models use 3+m parameters: alpha, sigma^2, and m+1 parameters to describe the expected trait values in each of the m+1 regimes. The AIC penalty is 2*(3+m). The BIC penalty is (3+m) * \log(n) where n is the numer of species. If one considers the position of the m shifts in the phylogeny as parameters (even though they are discrete parameters), we get the sAIC penalty 2*(3+2m) (used in SURFACE), and the sBIC penalty (3+2*m)*\log(n). The default penalty (model = 'mbic') is defined as 3*\log(n)+(2m-1)\log(n)+∑_{i=0}^{m}(\log(n_i)). A lower value of `nmax` will make the search faster, but if the estimated number of shifts is found equal to nmax, then the output model is probably not optimal. Re-running with a larger `nmax` would take longer, but would likely return a more complex model with a better score.

### Value

`y` | the input trait.
`phy` | the input tree.
`score` | the information criterion value of the optimal model.
`nmax` | maximum allowed number of shifts.
`nshift` | estimated number of shifts.
`alpha` | estimated selection strength of the optimal model.
`sigma2` | estimated variance of the optimal model.
`mean` | estimated the expected value of the trait in lineages without shift.
`pshift` | positions of shifts, i.e. indicies of edges where the estimated shifts occurred. The same ordering of edges is used as in phy.
`shift` | estimated shifts in the expected value of the trait.

### Note

The tip labels in the tree are matched to the data names. The default choice for the parameters are as follows: `method = "mbic"`, `check.pruningwise = TRUE`

Due to unidentifiability, the parameters are the expected value of the trait and their shifts instead of the ancestral trait, the optimal values and shifts in optimal values.

### Author(s)

Lam Si Tung Ho

### References

Ho, L. S. T. and Ane, C. 2014. "Intrinsic inference difficulties for trait evolution with Ornstein-Uhlenbeck models". Methods in Ecology and Evolution. 5(11):1133-1146.

Ingram, T. and Mahler, D.L. 2013. "SURFACE: detecting convergent evolution from comparative data by fitting Ornstein-Uhlenbeck models with step-wise Akaike information criterion". Methods in Ecology and Evolution 4:416-425.

Zhang, N.R. and Siegmund, D.O. 2007. "A modified Bayes information criterion with applications to the analysis of comparative genomic hybridization data". Biometrics 63:22-32.

### Examples

    data(flowerSize)
    data(flowerTree)
    result <- OUshifts(flowerSize$log_transformed_size, flowerTree,
                       method = "mbic", nmax = 1)
    plot.OUshifts(result,show.tip.label=FALSE)

[Package phylolm version 2.6.2 Index]