R: Creates a tree with branch lengths to represent the 3-point...

transf.branch.lengths {phylolm} | R Documentation

## 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 l is transformed to l^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 (exp(rate*t)-1)/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)

[Package phylolm version 2.6.2 Index]