castor (version 1.6.1)

root_at_midpoint: Root or re-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 midpoint node becomes the new root (i.e. has no incoming edges and all other tips and nodes descend from it). The number of tips and the number of nodes remain unchanged. The midpoint node is the node whose maximum distance to any tip is smallest.

Usage

root_at_midpoint( tree, 
                  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).

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.

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.

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.

Details

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, then node indices remain unchanged. If update_indices==TRUE (default), 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 reduces the computation required for rerooting. Tip indices always remain unchanged.

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

See Also

root_via_outgroup, root_at_node, root_in_edge

Examples

# NOT RUN {
# 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)
# }