R: Date a tree based on relative evolutionary divergences.

date_tree_red {castor} | R Documentation

## Date a tree based on relative evolutionary divergences.

### Description

Given a rooted phylogenetic tree and a single node ('anchor') of known age (distance from the present), rescale all edge lengths so that the tree becomes ultrametric and edge lengths correspond to time intervals. The function is based on relative evolutionary divergences (RED), which measure the relative position of each node between the root and its descending tips (Parks et al. 2018). If no anchor node is provided, the root is simply assumed to have age 1. This function provides a heuristic quick-and-dirty way to date a phylogenetic tree.

### Usage

    date_tree_red(tree, anchor_node = NULL, anchor_age = 1)

### Arguments

`tree` | A rooted tree of class "phylo". The root is assumed to be the unique node with no incoming edge.
`anchor_node` | Integer, ranging between 1 and Nnodes. Index of the node to be used as dating anchor. If `NULL`, the tree's root is used as anchor.
`anchor_age` | Positive numeric. Age of the anchor node.

### Details

The RED of a node measures its relative placement between the root and the node's descending tips (Parks et al. 2018). The root's RED is set to 0. Traversing from root to tips (preorder traversal), for each node the RED is set to P+(a/(a+b))\cdot(1-P), where P is the RED of the node's parent, a is the edge length connecting the node to its parent, and b is the average distance from the node to its descending tips. The RED of all tips is set to 1.

For each edge, the RED difference between child & parent is used to set the new length of that edge, multiplied by some common scaling factor to translate RED units into time units. The scaling factor is chosen such that the new distance of the anchor node from its descending tips equals `anchor_age`. All tips will have age 0. The topology of the dated tree, as well as tip/node/edge indices, remain unchanged.

This function provides a heuristic approach to making a tree ultrametric, and has not been derived from a specific evolutionary model. In particular, its statistical properties are unknown to the author.

The time complexity of this function is O(Nedges). The input tree may include multi-furcations (i.e. nodes with more than 2 children) as well as mono-furcations (i.e. nodes with only one child). If `tree$edge.length` is `NULL`, then all edges in the input tree are assumed to have length 1.

### Value

A list with the following elements:

`success` | Logical, indicating whether the dating was successful. If `FALSE`, all other return values (except for `error`) may be undefined.
`tree` | A new rooted tree of class "phylo", representing the dated tree.
`REDs` | Numeric vector of size Nnodes, listing the RED of each node in the input tree.
`error` | Character, listing any error message if `success==FALSE`.

### Author(s)

Stilianos Louca

### References

D. H. Parks, M. Chuvochina et al. (2018). A proposal for a standardized bacterial taxonomy based on genome phylogeny. bioRxiv 256800. DOI:10.1101/256800

### See Also

`congruent_divergence_times`

### Examples

    # generate a random non-ultrametric tree
    params = list(birth_rate_intercept=1, death_rate_intercept=0.8)
    tree = generate_random_tree(params, max_time=1000, coalescent=FALSE)$tree

    # make ultrametric, by setting the root to 2 million years
    dated_tree = date_tree_red(tree, anchor_age=2e6)

[Package castor version 1.6.7 Index]