Bind a tip to a phylogeny — bind

Graft a tip to a phylogeny at location specified.

Usage

bind_tip(
  tree = NULL,
  where,
  tip_label,
  frac = 0.5,
  new_node_above = FALSE,
  node_label = NULL,
  return_tree = TRUE,
  tree_tbl = NULL,
  node_heights = NULL,
  use_castor = TRUE,
  sequential = TRUE
)

Arguments

tree: A phylogeny, with class of "phylo".
where: Location where to insert the tip. It can be either tip label or node label, but must be characters. If the location does not have a name, assign it first.
tip_label: Name of the new tip inserted.
frac: The fraction of branch length, must be between 0 and 1. This only applies when location is a tip or new_node_above = TRUE. The distance from the new inserted node to the location (a node or a tip) is the branch length of the location * (1 - frac).
new_node_above: Whether to insert the new node above when the location is a node? Default is FALSE, which will attach the new tip to the location node.
node_label: Name of the new node created. This only applies when location is a tip or new_node_above = TRUE.
return_tree: Whether to return a phylogeny with class "phylo?" Default is TRUE. Otherwise, it will return a data frame.
tree_tbl: A tibble version of the tree, optional.
node_heights: A named numeric vector of node hieghts of the tree, generated by ape::branching.times(). It is also optional if tree is specified; but required if tree_tbl is specified.
use_castor: Whether to use package castor to get the phylogeny at a node; it is faster than tidytree::offspring to figure out what are the tip offsprings at a node.
sequential: Whether to add the tip with sequential node number in the edge matrix. For example, if we want to bind a tip to a clade and the node number of the tips of this clade is from 101 to 150. We can set the node id of the new tip to 151 and push all the remaining node id to 1 after their current values. This will require us to find out the node ids of all tips that are descents of the node where we want to bind the new tip to, and it can be time costly. Yet I am still not sure whether this is necessary. Normally, the node ids of the phylo class are sequential. Therefore, the default value here is TRUE. If set to FALSE, we can just assign the id of the new tip to Ntip + 1 to save time. In addition, we probably don't need to order the node column of the edge matrix every time.

Value

Either a phylogeny or a data frame, which can be then converted to a phylogeny later.

Examples

if (FALSE) {
library(rtrees)
bind_tip(tree_plant_otl, "N70407", tip_label = "test_sp")
tree_plant_otl_df = tidytree::as_tibble(tree_plant_otl)
node_heights = ape::branching.times(tree_plant_otl)
bind_tip(tree_tbl = tree_plant_otl_df, where = "N70407", 
         tip_label = "test_sp", node_heights = node_heights)
}