root_at_midpoint: Root a tree at the midpoint node.

In castor: Efficient Phylogenetics on Large Trees

Root a tree at the midpoint node.

Description

Given a tree (rooted or unrooted), this function changes the direction of edges (tree$edge) such that the new root satisfies a "midpoint"" criterion. The number of tips and the number of nodes remain unchanged. The root can either be placed on one of the existing nodes (this node will be the one whose maximum distance to any tip is minimized) or in the middle of one of the existing edges (chosen to be in the middle of the longest path between any two tips).

Usage

root_at_midpoint( tree, 
                  split_edge      = TRUE,
                  update_indices  = TRUE,
                  as_edge_counts  = FALSE,
                  is_rooted       = FALSE)

Arguments

tree	A tree object of class "phylo". Can be unrooted or rooted (but see option is_rooted).
split_edge	Logical, specifying whether to place the new root in the middle of an edge (in the middle of the longest path of any two tips), thereby creating a new node. If FALSE, then the root will be placed on one of the existing nodes; note that the resulting tree may no longer be bifurcating at the root.
update_indices	Logical, specifying whether to update the node indices such that the new root is the first node in the list, as is common convention. This will modify tree$node.label (if it exists) and also the node indices listed in tree$edge. Note that this option is only relevant if split_edge=FALSE; if split_edge=TRUE then update_indices will always be assumed TRUE.
as_edge_counts	Logical, specifying whether phylogenetic distances should be measured as cumulative edge counts. This is the same if all edges had length 1.
is_rooted	Logical, specifying whether the input tree can be assumed to be rooted. If you are not certain that the tree is rooted, set this to FALSE.

Details

The midpoint rooting method performs best if the two most distant tips have been sampled at the same time (for example, at the present) and if all lineages in the tree diverged at the same evolutionary rate. If the two most distant tips are sampled at very different times, for example if one or both of them represent extinct species, then the midpoint method is not recommended.

The input tree may include an arbitrary number of incoming and outgoing edges per node (but only one edge per tip), and the direction of these edges can be arbitrary. Of course, the undirected graph defined by all edges must still be a valid tree. Only set is_rooted=TRUE if you are sure that the input tree is rooted.

If update_indices==FALSE and split_edge=FALSE, then node indices remain unchanged. If update_indices==TRUE (default) or split_edge=TRUE, then node indices are modified such that the new root is the first node (i.e. with index Ntips+1 in edge and with index 1 in node.label), as is common convention. Setting update_indices=FALSE (when split_edge=FALSE) reduces the computation required for rerooting. Tip indices always remain unchanged.

The asymptotic time complexity of this function is O(Nedges).

Value

A tree object of class "phylo", with the edge element modified such that the maximum distance of the root to any tip is minimized. The elements tip.label, edge.length and root.edge (if they exist) are the same as for the input tree. If update_indices==FALSE, then the element node.label will also remain the same.

Author(s)

Stilianos Louca

See Also

root_via_outgroup, root_at_node, root_in_edge, root_via_rtt

Examples

# generate a random tree
Ntips = 100
tree = generate_random_tree(list(birth_rate_intercept=1),max_tips=Ntips)$tree

# reroot the tree at its midpoint node
tree = root_at_midpoint(tree)

castor documentation built on June 29, 2024, 9:08 a.m.