castor (version 1.6.1)

root_via_outgroup: Root or re-root a tree based on an outgroup tip.

Description

Given a tree (rooted or unrooted) and a specific tip (``outgroup''), this function changes the direction of edges (tree$edge) such that the outgroup's parent node becomes the root. The number of tips and the number of nodes remain unchanged.

Usage

root_via_outgroup(tree, outgroup, update_indices=TRUE)

Arguments

tree

A tree object of class "phylo". Can be unrooted or rooted.

outgroup

Character or integer specifying the name or index, respectively, of the outgroup tip. If an integer, it must be between 1 and Ntips. If a character, it must be a valid entry in tree$tip.label.

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.

Value

A tree object of class "phylo", with the edge element modified such that the outgroup tip's parent node is root. 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. The asymptotic time complexity of this function is O(Nedges).

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). This is common convention, but it may be undesirable in some cases. Setting update_indices=FALSE also reduces the computation required for rerooting. Tip indices always remain unchanged.

See Also

root_at_node, root_at_midpoint, 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 using the 1st tip as outgroup
outgroup = 1
tree = root_via_outgroup(tree, outgroup, update_indices=FALSE)

# find new root index
cat(sprintf("New root is %d\n",find_root(tree)))
# }