root_in_edge {castor}

Root a tree in the middle of an edge.

Description

Given a tree (rooted or unrooted), this function places the new root on some specified edge, effectively adding one more node, one more edge and changing the direction of edges as required.

Usage

root_in_edge( tree, 
              root_edge, 
              location                = 0.5,
              new_root_name           = "", 
              collapse_monofurcations = TRUE)

Arguments

tree

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

root_edge

Integer, index of the edge into which the new root is to be placed. Must be between 1 and Nedges.

location

Numeric, between 0 and 1, specifying the relative location along the root_edge at which to place the root (relative to the edge length, measured from the upstream node). For example, location=0.5 means the root is placed in the middle of the edge, while location=0.1 means that it will be place closer to the upstream node (i.e., closer to tree$edge[root_edge,1]).

new_root_name

Character, specifying the node name to use for the new root. Only used if tree$node.label is not NULL.

collapse_monofurcations

Logical, specifying whether monofurcations in the rerooted tree (e.g. stemming from the old root) should be collapsed by connecting incoming edges with outgoing edges.

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 number of tips in the rerooted tree remains unchanged, the number of nodes is increased by 1. Node indices may be modified. Tip indices always remain unchanged.

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

Value

A tree object of class "phylo", representing the (re-)rooted phylogenetic tree. The element tip.label is the same as for the input tree, but all other elements may have changed.

Author(s)

Stilianos Louca

See Also

root_via_outgroup, root_at_node, root_at_midpoint, 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 inside some arbitrary edge
focal_edge = 120
tree = root_in_edge(tree, focal_edge)