R: Eliminate short edges in a tree by merging nodes into...

merge_short_edges {castor} | R Documentation

## Eliminate short edges in a tree by merging nodes into multifurcations.

### Description

Given a rooted phylogenetic tree and an edge length threshold, merge nodes/tips into multifurcations when their incoming edges are shorter than the threshold.

### Usage

    merge_short_edges(tree,
                      edge_length_epsilon	= 0,
                      force_keep_tips     = TRUE,
                      new_tip_prefix      = "ex.node.tip.")

### Arguments

`tree` | A rooted tree of class "phylo". The root is assumed to be the unique node with no incoming edge.
`edge_length_epsilon` | Non-negative numeric, specifying the maximum edge length for an edge to be considered “short” and thus to be eliminated. Typically 0 or some small positive number.
`force_keep_tips` | Logical. If `TRUE`, then tips are always kept, even if their incoming edges are shorter than `edge_length_epsilon`. If `FALSE`, then tips with short incoming edges are removed from the tree; in that case some nodes may become tips.
`new_tip_prefix` | Character or `NULL`, specifying the prefix to use for new tip labels stemming from nodes. Only relevant if `force_keep_tips==FALSE`. If `NULL`, then labels of tips stemming from nodes will be the node labels from the original tree (in this case the original tree should include node labels).

### Details

The input tree may include multi-furcations (i.e. nodes with more than 2 children) as well as mono-furcations (i.e. nodes with only one child). Whenever a short edge is eliminated, the edges originating from its child are elongated according to the short edge's length. The corresponding grand-children become children of the short edge's parent. Short edges are eliminated in a depth-first-search manner, i.e. traversing from the root to the tips.

Note that existing monofurcations are retained. If `force_keep_tips==FALSE`, then new monofurcations may also be introduced due to tips being removed.

This function is conceptually similar to the function `ape::di2multi`.

### Value

A list with the following elements:

`tree` | A new rooted tree of class "phylo", containing the (potentially multifurcating) tree.
`new2old_clade` | Integer vector of length equal to the number of tips+nodes in the new tree, with values in 1,..,Ntips+Nnodes, mapping tip/node indices of the new tree to tip/node indices in the original tree.
`new2old_edge` | Integer vector of length equal to the number of edges in the new tree, with values in 1,..,Nedges, mapping edge indices of the new tree to edge indices in the original tree.
`Nedges_removed` | Integer. Number of edges that have been eliminated.

### Author(s)

Stilianos Louca

### See Also

`multifurcations_to_bifurcations`

### Examples

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

    # set some edge lengths to zero
    tree$edge.length[sample.int(n=Ntips, size=10, replace=FALSE)] = 0

    # print number of edges
    cat(sprintf("Original tree has %d edges\n",nrow(tree$edge)))

    # eliminate any edges of length zero
    merged = merge_short_edges(tree, edge_length_epsilon=0)$tree

    # print number of edges
    cat(sprintf("New tree has %d edges\n",nrow(merged$edge)))

[Package castor version 1.7.0 Index]