merge_nodes_to_multifurcations: Merge specific nodes into multifurcations.

In castor: Efficient Phylogenetics on Large Trees

Merge specific nodes into multifurcations.

Description

Given a rooted tree, merge one or more nodes “upwards” into their parent nodes, thus effectively generating multifurcations. Multiple generations of nodes (i.e., successive branching points) can be merged into a single "absorbing ancestor".

Usage

merge_nodes_to_multifurcations( tree, 
                                nodes_to_merge,
                                merge_with_parents  = FALSE,
                                keep_ancestral_ages = FALSE)

Arguments

tree	A rooted tree of class "phylo".
nodes_to_merge	Integer vector or character vector, listing nodes in the tree that should be merged with their parents (if merge_with_parents=TRUE) or with their children (if merge_with_parents=FALSE). If an integer vector, it must contain values in 1,..,Nnodes. If a character vector, it must list node labels, and the tree itself must also include node labels.
merge_with_parents	Logical, specifying whether the nodes listed in nodes_to_merge should be merged with their parents. If FALSE, the specified nodes will be merged with their children (whenever these are not tips).
keep_ancestral_ages	Logical, specifying whether the generated multifurcations should have the same age as the absorbing ancestor. If FALSE, then the age of a multifurcation will be the average of the absorbing ancestor's age and the ages of its merged child nodes (but constrained from below by the ages of non-merged descendants to avoid negative edge lengths). If TRUE, then the ages of multifurcations will be biased towards the root, since their age will be that of the absorbing ancestor.

Details

All tips in the input tree are kept and retain their original indices, however the returned tree will include fewer nodes and edges. Edge and node indices may change. When a node is merged into its parent, the incoming edge is lost, and the parent's age remains unchanged.

Nodes are merged in order from root to tips. Hence, if a node B is merged into ("absorbed by") its parent node A, and child node C is merged into node B, then effectively C ends up merged into node A (node A is the "absorbing ancestor").

If tree$edge.length is missing, then all edges in the input tree are assumed to have length 1.

Value

A list with the following elements:

tree	A new tree of class "phylo". The number of nodes in this tree, Nnodes_new, will generally be lower than of the input tree.
new2old_node	Integer vector of length Nnodes_new, mapping node indices in the new tree to node indices in the old tree. Note that nodes merged with their parents are not represented in this list.
old2new_node	Integer vector of length Nnodes, mapping node indices in the old tree to node indices in the new tree. Nodes merged with their parents (and thus missing from the new tree) will have value 0.
Nnodes_removed	Integer. Number of nodes removed from the tree, due to being merged into their parents.
Nedges_removed	Integer. Number of edges removed from the tree.

Author(s)

Stilianos Louca

See Also

multifurcations_to_bifurcations, collapse_monofurcations

Examples

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

# merge a few nodes with their parents,
# thus obtaining a multifurcating tree
nodes_to_merge = c(1,3,4)
new_tree = merge_nodes_to_multifurcations(tree, nodes_to_merge)$tree

# print summary of old and new tree
cat(sprintf("Old tree has %d nodes\n",tree$Nnode))
cat(sprintf("New tree has %d nodes\n",new_tree$Nnode))

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