transf.branch.lengths {phylolm}

Creates a tree with branch lengths to represent the 3-point structure of a covariance matrix

Description

Creates a phylogenetic tree with branch lengths and a diagonal matrix to represent a (generalized) 3-point structured covariance matrix from a trait evolution model on a known tree.

Usage

transf.branch.lengths(phy, model = c("BM", "OUrandomRoot",
       "OUfixedRoot", "lambda", "kappa", "delta", "EB", "trend"),
       parameters = NULL, check.pruningwise = TRUE,
       check.ultrametric=TRUE, D=NULL, check.names = TRUE)

Arguments

phy

a phylogenetic tree of type phylo with branch lengths.

model

a phylogenetic model. Default is "BM", for Brownian motion. Alternatives are "OU", "lambda", "kappa", "delta", "EB" and "trend".

parameters

List of parameters for the model (see Note).

check.pruningwise

if FALSE, the tree is assumed to be in pruningwise order.

check.ultrametric

if FALSE, the tree is assumed to be ultrametric and D needs to be provided. This is used for the OU transformations only.

D

vector of ajustments for the external edge lengths, to make the tree ultrametric. Used for the OU transformations only.

check.names

D needs to have names that match tip labels unless check.names=FALSE, in which case the elements in D are assumed to come in the same order as tip labels in the tree.

Details

Possible phylogenetic models are the Brownian motion model (BM), the Ornstein-Uhlenbeck model (OU), Pagel's lambda model (lambda), Pagel's kappa model (kappa), Pagel's delta model (delta), the early burst model (EB), and the Brownian motion with a trend (trend). Edge lengths are unchanged under BM and the trend model. Under the kappa model, each branch length \ell is transformed to \ell^\kappa. If the time from the root to a node is t in phy, it is transformed to T * (t/T)^\delta under the delta model, where T is the maximum root-to-tip distance. The transformed tree has the same T. Under EB, t is transformed to (e^{\mathrm{rate}*t}-1)/\mathrm{rate}, which is very close to t (i.e. to the BM model) when rate is close to 0. Under the lambda model, the time t from the root to a node is transformed to \lambda t for an internal node and is unchanged for a tip. Under "OUrandomRoot", t is transformed to \exp(-2\alpha (T-t)), where T is now the mean root-to-tip distance. Under "OUfixedRroot", t is transformed to \exp(-2\alpha (T-t))(1-\exp(-2 \alpha t)). Under the OU models, diagWeight contains \exp(\alpha D_i) for tip i, where D_i is the extra length added to tip i to make the tree ultrametric.

Value

tree

a rooted tree with a root edge and transformed branch lengths.

diagWeight

a vector containing the diagonal elements of the diagonal matrix for the generalized 3-point structure.

Note

The default choice for the parameters are as follows: alpha=0 for the selection strength in the OU model, lambda=1, kappa=1, delta=1, rate=0 for the EB model, sigma2_error=0 for the variance of measurement errors. These default choices correspond to the BM model.

Edges in the output tree are in pruningwise order.

If model="BM" or model="trend", the output tree is the same as the input tree except that the output tree is in pruningwise order.

Author(s)

Lam Si Tung Ho

References

Ho, L. S. T. and Ane, C. A linear-time algorithm for Gaussian and non-Gaussian trait evolution models. Systematic Biology 63(3):397-408.

See Also

three.point.compute.

Examples

set.seed(123456)
tre1 = rcoal(10)
tre2 = transf.branch.lengths(phy=tre1, model="OUrandomRoot",
                             parameters = list(alpha=1))
par(mfrow = c(2,1))
plot(tre1)
plot(tre2$tree,root.edge=TRUE)