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

In lamho86/phylolm: Phylogenetic Linear Regression

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)+\sum_{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)

lamho86/phylolm documentation built on Nov. 11, 2023, 6:17 a.m.